从零完整实操：Python MCP服务打包、发布到Smithery、本地安装调用全流程
从零完整实操：Python MCP服务打包、发布到Smithery、本地安装调用全流程
前言
Model Context Protocol（MCP）是Anthropic推出的AI工具标准，允许开发者自定义工具服务，给Claude、Cursor、RooCode等AI客户端扩展能力。Smithery是目前主流的MCP开源仓库，支持一键打包、发布、分发、本地安装MCP服务。
本文以Python天气查询MCP服务为例，完整记录从项目初始化、打包、发布上架、本地拉取安装、接入AI客户端的全流程，踩坑点全部标注，新手可直接复刻。
一、环境前置准备
1. 全局工具安装
需要两个核心CLI工具：@anthropic-ai/mcpb（打包MCP包）、@smithery/cli（Smithery仓库管理）
# 安装MCP打包工具
npm install -g @anthropic-ai/mcpb
# 安装Smithery官方命令行
npm install -g @smithery/cli
2. Smithery账号登录
发布服务前必须登录账号，执行命令唤起浏览器授权：
smithery auth login
验证登录状态：
smithery auth status
注意：登录后的账号数字ID，就是后续发布命令的命名空间（namespace），不可随意修改。
3. 项目目录结构
本文示例项目：weather-mcp-server，Python实现的天气MCP服务
weather-mcp-server/
├─ server.py # MCP服务启动入口
├─ requirements.txt # Python依赖
├─ manifest.json # mcpb init生成的打包配置（核心）
├─ server.mcpb # mcpb pack生成的打包产物
└─ 其他说明/配置文件
不过在官方mcpb的介绍中，仅需要manifest.json就可以上传，这边一般加上依赖应该是方便了解
二、初始化MCP打包配置（mcpb init）
进入项目根目录，执行初始化命令生成manifest.json配置文件：
mcpb init
交互式参数填写完整说明（对应实操踩坑点）
- Extension name：内部唯一标识，纯英文小写，示例
server - Author name：作者名，和Smithery账号保持一致，示例
cwk - Display name：客户端展示名称（可选，支持中文），示例
天气查询MCP工具 - Version：语义化版本，初次发布固定
1.0.0 - Description：一句话工具简介，如
提供实时城市天气查询的Python MCP服务 Add a detailed long description?：测试选no，正式开源可填yes- Author邮箱、主页、文档链接：个人测试全部回车留空跳过
- Icon、截图配置：测试全部选
no跳过 Server type：代码语言，Python项目选Python- Entry point：服务启动入口文件（重点！）
- 入口文件在项目根目录：直接填
server.py - 入口文件在子文件夹：填
server/main.py
禁止填写Windows绝对路径，仅支持相对manifest.json的路径
- 入口文件在项目根目录：直接填
Add compatibility constraints?：测试选no，不限制客户端版本Add user-configurable options?：如果你的工具需要用户填写密钥/参数（如天气API Key），选yesConfiguration option key：配置项底层键名，示例weather_api_key（仅英文下划线）- 后续依次填写配置展示名、描述、类型
string、必填yes，无默认值回车跳过
执行完成后，项目根目录自动生成manifest.json，是打包、发布的核心配置文件。
三、打包生成MCPB安装包
配置文件就绪后，一键打包生成server.mcpb压缩包（Smithery标准离线分发包）：
mcpb pack
执行后目录出现server.mcpb，代表打包完成，可用于上传发布。
四、发布MCP服务到Smithery公共仓库
1. 发布命令格式
smithery mcp pack ./server.mcpb -n 你的账号ID/工具名
实操示例（避坑重点）
- 账号ID：登录Smithery后，个人主页数字ID，不可自定义
- 工具名：打包时extension name，全程拼写必须统一，大小写、字母不能错
本次实操正确命令：
smithery mcp publish ./yourserver.mcpb -n namespace/weather-mcp-serve
发布流程输出解读
Server xxx doesn't exist yet. Create it? Yes：首次发布输入Yes，自动在你的账号下创建服务条目Created server xxx：服务条目创建成功Release xxx accepted：打包文件校验上传完成Release successful!：发布流程全部完成- 输出两条关键链接：
- MCP远程URL：云端运行地址，可直接给AI客户端接入远程服务
- Server Page：工具公开详情页，可编辑介绍、修改可见性、查看运行日志
关键状态说明
刚发布的服务默认是unlisted（未公开）状态：
- 市场搜索不到，仅持有链接的人可访问
- 如需公开上架，进入页面点击
Change visibility切换为Public
五、本地拉取、安装、调用已发布的MCP服务
前置说明
旧命令smithery install已废弃，官方推荐使用smithery mcp add/smithery mcp pull
方式1：绑定AI客户端一键安装（推荐）
1. 先删除错误创建的连接（拼写错误时）
smithery mcp remove 错误的工具名
2. 正确添加服务（严格匹配发布时的名称）
smithery install namespace/仓库名
这样会选择比如cursor、claude、tome等客户端
3. 选择目标AI客户端
执行后弹出客户端列表，按需选择：
claude-desktop：Claude桌面客户端（最常用，向下翻页可见）roocode：VSCode RooCode插件cursor：Cursor编辑器AI
选择完成后，输入打包时配置的必填参数weather_api_key，自动写入客户端配置。
方式2：仅本地下载源码，不绑定客户端
仅拉取代码到本地，自行调试：
smithery mcp add namespace/weather-mcp-serve
本地验证工具是否可用
安装完成后，列出服务内置的所有工具函数：
smithery tool list weather-mcp-serve
调用工具测试：
smithery tool call weather-mcp-serve get_weather '{"city":"北京"}'
六、高频踩坑汇总（实操避坑）
- 名称拼写不一致404报错
发布时工具名weather-mcp-serve，安装时写成weather-mcp-server（多r），路径不存在，严格复制详情页链接内的服务全名。 - 入口文件路径填写错误
mcpb init的entry point仅支持相对路径，禁止Windows绝对路径，文件不存在会导致服务启动失败。 - 云端无工具能力
No capabilities found
云端环境不会自动安装requirements.txt依赖，且缺少用户配置的API密钥；本地安装会自动处理依赖，无此问题。 - 个人主页看不到刚发布的服务
① 服务默认隐藏unlisted状态，切换Public后刷新；② Smithery列表存在缓存延迟，等待3-5分钟；③ 网页登录账号和终端登录账号不一致。 smithery install命令废弃
黄色警告提示无需慌张，改用smithery mcp add标准命令即可。
七、更新已发布的MCP服务
修改server.py代码或配置后，重新打包+发布，自动生成新版本覆盖仓库：
# 重新打包
mcpb pack
# 重新发布，名称和初次发布保持完全一致
smithery mcp publish ./server.mcpb -n namespace/weather-mcp-serve
总结
- 打包流程：
mcpb init生成配置 →mcpb pack输出.mcpb包； - 发布流程：登录Smithery →
smithery mcp publish上传包，生成公开服务； - 本地使用：
smithery mcp add绑定AI客户端，填写密钥后直接调用自定义工具； - 核心注意点：账号ID、工具名称全程拼写统一，入口路径使用相对路径，区分云端/本地运行的环境差异。
整套流程打通后，你可以自由开发任意自定义MCP工具（文件处理、数据库、联网搜索、第三方API封装等），一键分发到Smithery，供自己或其他开发者在各类AI客户端中使用。
smithery更改版本比较快，很多文章过时了参考意义不大，本文章是在学习hello-agents的过程中，出现了smithery上传不上的问题，因此拿出自己的经历进行分享，目前好像是不再支持可以填入github路径进行部署了，只能命令行和在线服务器上传。
浙公网安备 33010602011771号