动手制作你的第一个 MCP Server
配套阅读:《MCP原理详解.md》。本文带你从零写一个能在 Claude Desktop / WorkBuddy 等 Host 里真正跑起来的 MCP 服务器,最后还会”裸写 JSON-RPC”验证你理解了协议本身。
全程约 30 分钟,只需要 Python 3.10+(或 Node.js 18+,文末附 TS 版提示)。
1. 我们要做什么
做一个名叫 demo-mcp 的服务器,包含:
| 原语 | 内容 | 对应规范 |
|---|---|---|
| Tool | add 两数相加 |
最小可用的工具 |
| Tool | list_dir 列出目录文件(带只读注解) |
演示参数校验、错误处理、注解 |
| Resource | memo://notes 内存备忘录 |
演示资源 |
| Prompt | greet 问候模板 |
演示提示模板 |
做完后你会拥有:一个通过 stdio 与 Host 通信、可被模型调用的标准 MCP 服务器。
2. 准备工作
2.1 环境要求
- **Python 3.10+**(
python --version确认) - pip 可用
2.2 安装官方 Python SDK
# 方式一:直接用 pip(最简单)
pip install "mcp[cli]<2"
# 方式二:venv 隔离(推荐,避免污染全局环境)
py -m venv .venv
.venv\Scripts\activate # Windows cmd
# source .venv/bin/activate # macOS / Linux
python -m pip install "mcp[cli]<2"
**⚠️ 一定要加
<2**:mcp2.x 把FastMCP改名为MCPServer(from mcp.server.mcpserver import MCPServer),本文第 3 步的代码在 2.x 下会直接ModuleNotFoundError: No module named 'mcp.server.fastmcp'。想用 2.x 新 API 请参考官方迁移指南,本文按稳定的 1.x 编写(mcp==1.30.0实测通过)。
关于 uv:uv 不是 Python 自带的,需要单独安装(pip install uv 或官方安装脚本)。很多环境里装完还不在 PATH 里,直接 uv 会报”不是内部或外部命令”。不确定就用上面的 venv 方案,一条弯路都不用走。
mcp[cli] 包含三样东西:
mcp库本体(协议实现 + FastMCP 高层 API);mcp dev/mcp run开发命令;- MCP Inspector 自动集成的启动入口。
Windows 提示:本文命令均以
.venv\Scripts\python.exe server.py形式给出,与是否激活虚拟环境无关,最稳妥。
3. 第 1 步:写出第一个 MCP Server
新建 server.py:
"""
demo-mcp:我的第一个 MCP 服务器
传输方式:stdio(被 Host 作为子进程启动)
"""
import os
from mcp.server.fastmcp import FastMCP
# 创建服务器实例,name 会出现在 serverInfo 里
mcp = FastMCP("demo-mcp")
# ---------- 内存备忘录(供 Resource 使用) ----------
NOTES: dict[str, str] = {
"todo": "1. 学完 MCP 原理\n2. 写自己的第一个 Server\n3. 接入 Host",
}
# ---------- Tool 1:两数相加 ----------
@mcp.tool()
def add(a: int, b: int) -> int:
"""把两个整数相加,返回它们的和。"""
return a + b
# ---------- Tool 2:列出目录内容 ----------
@mcp.tool(
annotations={
"title": "列出目录",
"readOnlyHint": True, # 只读操作,Host 可以放心预览
"idempotentHint": True,
},
)
def list_dir(path: str = ".") -> str:
"""列出指定目录下的文件和子目录名。path 为目录路径,默认当前目录。"""
try:
entries = sorted(os.listdir(path))
except FileNotFoundError:
# 业务错误:返回 isError 结果让"模型"看到,而不是抛协议异常
raise ValueError(f"目录不存在: {path}")
except PermissionError:
raise ValueError(f"没有权限访问: {path}")
if not entries:
return f"{path} 是空目录"
lines = [f"📁 {path} 下共 {len(entries)} 项:"]
for name in entries:
full = os.path.join(path, name)
tag = "🗂" if os.path.isdir(full) else "📄"
lines.append(f"{tag} {name}")
return "\n".join(lines)
# ---------- Resource:备忘录 ----------
@mcp.resource("memo://notes")
def get_notes() -> str:
"""读取用户的备忘录内容。"""
return "\n".join(f"[{k}]\n{v}" for k, v in NOTES.items())
# ---------- Prompt:问候模板 ----------
@mcp.prompt()
def greet(name: str) -> str:
"""生成一段问候用户的提示词模板。"""
return f"请用温暖友好的语气向 {name} 打个招呼,并简单介绍一下你能做什么。"
# ---------- 启动 ----------
if __name__ == "__main__":
# ⚠️ 只用 stdio 传输;千万不要在 main 里 print 任何东西污染 stdout
mcp.run(transport="stdio")
关于这份代码的几个关键点:
@mcp.tool()会把函数签名自动转成 JSON Schema:类型注解a: int→inputSchema,docstring → 工具description。所以 docstring 就是给模型看的说明书,写清楚”何时该用这个工具”能显著提高调用准确率;- **业务错误用
raise ValueError**:FastMCP 会把它包装成isError: true的结果返回给模型(模型能看到错误文字并重试/换路),而不是打断会话的协议错误; annotations是给 Host/用户的行为提示,不是安全保证——真正的写入类操作仍需 Host 弹窗审批;- stdout 纪律:
mcp.run(transport="stdio")之外,任何print()都会让 Host 解析失败。调试信息用logging(默认走 stderr)。
本地直接运行验证
# 未激活虚拟环境时(最稳妥,路径不会错)
.venv\Scripts\python.exe server.py
# 已激活虚拟环境时
python server.py
# 没有输出 = 正常!它在等 stdin 上的 JSON-RPC 消息(下一步手动喂给它)
# Ctrl+C 退出
4. 第 2 步:用 MCP Inspector 调试
官方 Inspector 是开发 MCP 的必备工具,提供网页 UI 逐个调用你的工具/资源/提示:
# 用虚拟环境里的 mcp 命令(Windows)
.venv\Scripts\mcp.exe dev server.py
# 已激活虚拟环境时
mcp dev server.py
# 不用 cli 时(任意环境)
npx @modelcontextprotocol/inspector .venv\Scripts\python.exe server.py
会打开 http://localhost:6274(Inspector 面板)。依次检查:
- Connect:确认握手成功,面板显示
demo-mcp与协议版本; - Tools 标签:看到
add和list_dir→ 输入{"a": 2, "b": 40}运行add,应返回42;用list_dir列一个真实目录和一个不存在的目录,观察isError结果; - Resources 标签:读取
memo://notes; - Prompts 标签:填
name后Get Prompt,看到生成的 messages。
调试习惯建议:每次改动代码先过一遍 Inspector,再接 Host——Host 报错往往只有一行日志,Inspector 的报错则精确到参数 schema。
5. 第 3 步:接入 Host(Claude Desktop / WorkBuddy)
5.1 Claude Desktop
编辑配置文件(菜单 File → Settings → Developer → Edit Config):
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"demo-mcp": {
"command": "C:/Users/你的用户名/projects/demo-mcp/.venv/Scripts/python.exe",
"args": ["C:/Users/你的用户名/projects/demo-mcp/server.py"]
}
}
}
要点:
command指向 venv 里的 python 绝对路径,args指向 server.py 绝对路径——这样不依赖系统 PATH,也不会用错 Python 版本;- 不用 venv 时
"command": "python"也可以,但前提是那个python里装好了mcp(用python -c "import mcp"验证); - Windows 下如果用
npx/uvx启动的服务器,标准写法是"command": "cmd", "args": ["/c", "npx", "-y", "包名"]; - 保存后完全退出并重启 Claude Desktop(托盘图标也要退),锤子图标(工具)出现即接入成功;
- 日志排障:
%APPDATA%\Claude\logs\mcp-server-demo-mcp.log(Windows)或~/Library/Logs/Claude/(macOS)。
5.2 WorkBuddy
WorkBuddy 的 MCP 配置写在 ~/.workbuddy/mcp.json(注意是 mcp.json,不是 .mcp.json),格式与上面一致。写入后不会自动生效——需要到连接器管理页顶部”自定义连接器”里对新服务器点击”信任“来启用。
{
"mcpServers": {
"demo-mcp": {
"command": "D:/projects/demo-mcp/.venv/Scripts/python.exe",
"args": ["D:/projects/demo-mcp/server.py"],
"env": { "DEMO_MODE": "local" }
}
}
}
env 字段可以给子进程传环境变量(API Key 等)——Key 只写在配置里,永远不要写死在 server 代码中。
5.3 验收测试
在 Host 对话里试这几句:
- “帮我算 12345 + 6789” → Host 应请求批准并调用
add; - “列出 D:/projects 目录下有什么” →
list_dir; - “读一下我的备忘录” → 走 Resource;
- 输入
/greet或”用 greet 提示词向小明打招呼” → Prompt 模板展开。
如果 Host 询问”是否允许调用 demo-mcp 的 add 工具”,恭喜——你正亲眼看到第 8 节安全模型(用户审批)在真实运行。
6. 第 4 步:裸写 JSON-RPC,看透协议
SDK 把协议藏了起来,但我们手动发四条消息,就能亲眼看到 MCP 的本质。写 talk.py,把上一节 server.py 当子进程跑:
"""手动驱动 MCP 服务器:向子进程 stdin 写 JSON-RPC,读 stdout 响应"""
import json
import subprocess
import sys
proc = subprocess.Popen(
[sys.executable, "server.py"],
stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
text=True, encoding="utf-8",
)
def send(msg: dict, expect_reply: bool = True):
line = json.dumps(msg, ensure_ascii=False)
print(f"\n>>> {line}")
proc.stdin.write(line + "\n")
proc.stdin.flush()
if expect_reply:
reply = proc.stdout.readline().strip()
print(f"<<< {reply}")
return json.loads(reply)
# 1) 握手:交换版本与能力
send({
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {"name": "manual-client", "version": "0.1"},
},
})
# 2) 握手完成通知(无 id、无响应)
send({"jsonrpc": "2.0", "method": "notifications/initialized"}, expect_reply=False)
# 3) 列出工具
send({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})
# 4) 调用工具
send({
"jsonrpc": "2.0", "id": 3, "method": "tools/call",
"params": {"name": "add", "arguments": {"a": 2, "b": 40}},
})
proc.terminate()
python talk.py
tools/call 的响应长这样(节选):
{
"jsonrpc": "2.0", "id": 3,
"result": { "content": [{ "type": "text", "text": "42" }] }
}
对照《MCP原理详解.md》第 5.4 节:这四条消息就是 MCP 的全部核心报文。SDK、Inspector、Host 都只是在帮你生成和解析这些行。
顺手做三个协议实验(以下是实测结果)
参数类型传错:把
tools/call改成{"name": "add", "arguments": {"a": "x", "b": 2}}→ 收到的不是协议错误,而是isError: true的结果:{"content":[{"type":"text","text":"Error executing tool add: 1 validation error for addArguments ..."}],"isError":true}这正是第 6 章讲的语义:参数/业务错误交给模型看,会话不中断,模型可以自行改参数重试。
调用不存在的工具:
{"name": "nope"}→ 同样是isError结果,文本为Unknown tool: nope(FastMCP 的友好处理)。请求不存在的方法:发
{"method": "foo/bar"}→ 这时才是协议级错误:{"error":{"code":-32602,"message":"Invalid request parameters","data":""}}污染 stdout:在
server.py顶部加一行print("hello")→ Host/Inspector 立刻连接失败——体会”stdout 纪律”铁律,改完记得删掉。
7. 进阶方向
按实用性排序:
- HTTP 部署(Streamable HTTP):
mcp.run(transport="streamable-http"),让远程团队共享同一个 Server;生产环境记得加 TLS + OAuth,并关注 2026-07-28 规范的无状态化设计(server/discover、每请求_meta、Mcp-Method头); - 结构化输出:给工具声明
outputSchema返回structuredContent,让下游更可解析(2025-06-18+); - 长任务:耗时操作用进度通知(
progressToken)反馈;2026-07-28 的 Tasks 扩展提供轮询式长任务模型; - Sampling / Elicitation:让服务器反过来请求 Host 调 LLM 或向用户要确认(记得这三个客户端原语的共同哲学:能力在服务器、权力在客户端);
- TypeScript 版:
@modelcontextprotocol/sdk,McpServer+registerTool,结构与本文一一对应; - 发布:打包成
uvx/npx一键启动的包,写进 README 的 mcpServers 配置片段,别人复制粘贴就能用。
8. 排障清单
| 症状 | 最可能原因 | 解法 |
|---|---|---|
| Host 完全连不上、无工具图标 | 配置文件路径错 / JSON 语法错 | 用 JSON 校验器检查;确认绝对路径 |
日志里 Unexpected token ... in JSON |
服务器向 stdout 打印了非 MCP 内容 | 移除所有 print,调试用 logging(stderr) |
工具列表出现但调用报 Invalid params |
参数类型注解与传参不符 | Inspector 里先跑通,检查 int/str 注解 |
| Windows 下 npx 型服务器连不上 | 没有经 cmd 包装 |
"command": "cmd", "args": ["/c", "npx", "-y", "pkg"] |
uv 不是内部或外部命令 |
uv 需单独安装,且常不在 PATH | 改用 venv 方案,或 pip install uv 后用全路径调用 |
No module named 'mcp.server.fastmcp' |
装到了 mcp 2.x(FastMCP 改名 MCPServer) | pip install "mcp[cli]<2" 重装 |
| Claude Desktop 改了配置没反应 | 没有彻底重启 | 托盘右键 Quit 后重开 |
| 工具被调用但返回乱码/超时 | 输出未按换行分隔,或子进程卡死 | 确认每条消息单行;本地跑 .venv\Scripts\python.exe server.py 看是否阻塞 |
| 远程服务器 403 | Origin 校验失败 / 未带 Accept 头 | 按规范带 Origin 与 Accept: application/json, text/event-stream |
收尾检查清单
-
.venv\Scripts\python.exe server.py启动后零输出(stdout 干净) - Inspector 里 2 个工具 + 1 个资源 + 1 个提示全部可调
-
add返回 42;list_dir传错路径返回isError文本而非崩溃 - Host 配置已写入、重启后出现工具入口
-
talk.py能看到 4 条 JSON-RPC 报文往返 - 代码里没有任何硬编码密钥(走
env)
完成以上全部,你就已经从一个”MCP 用户”变成了”MCP 开发者”。下一步建议:挑一个你每天重复做的手工操作(查某个内部系统、整理某类文件),把它做成第二个工具。