动手制作你的第一个 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**:mcp 2.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")

关于这份代码的几个关键点:

  1. @mcp.tool() 会把函数签名自动转成 JSON Schema:类型注解 a: int → inputSchema,docstring → 工具 description。所以 docstring 就是给模型看的说明书,写清楚”何时该用这个工具”能显著提高调用准确率;
  2. **业务错误用 raise ValueError**:FastMCP 会把它包装成 isError: true 的结果返回给模型(模型能看到错误文字并重试/换路),而不是打断会话的协议错误;
  3. annotations 是给 Host/用户的行为提示,不是安全保证——真正的写入类操作仍需 Host 弹窗审批;
  4. 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 面板)。依次检查:

  1. Connect:确认握手成功,面板显示 demo-mcp 与协议版本;
  2. Tools 标签:看到 add 和 list_dir → 输入 {"a": 2, "b": 40} 运行 add,应返回 42;用 list_dir 列一个真实目录和一个不存在的目录,观察 isError 结果;
  3. Resources 标签:读取 memo://notes;
  4. 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 都只是在帮你生成和解析这些行。

顺手做三个协议实验(以下是实测结果)

  1. 参数类型传错:把 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 章讲的语义:参数/业务错误交给模型看,会话不中断,模型可以自行改参数重试。

  2. 调用不存在的工具:{"name": "nope"} → 同样是 isError 结果,文本为 Unknown tool: nope(FastMCP 的友好处理)。

  3. 请求不存在的方法:发 {"method": "foo/bar"} → 这时才是协议级错误:

    {"error":{"code":-32602,"message":"Invalid request parameters","data":""}}
  4. 污染 stdout:在 server.py 顶部加一行 print("hello") → Host/Inspector 立刻连接失败——体会”stdout 纪律”铁律,改完记得删掉。


7. 进阶方向

按实用性排序:

  1. HTTP 部署(Streamable HTTP):mcp.run(transport="streamable-http"),让远程团队共享同一个 Server;生产环境记得加 TLS + OAuth,并关注 2026-07-28 规范的无状态化设计(server/discover、每请求 _meta、Mcp-Method 头);
  2. 结构化输出:给工具声明 outputSchema 返回 structuredContent,让下游更可解析(2025-06-18+);
  3. 长任务:耗时操作用进度通知(progressToken)反馈;2026-07-28 的 Tasks 扩展提供轮询式长任务模型;
  4. Sampling / Elicitation:让服务器反过来请求 Host 调 LLM 或向用户要确认(记得这三个客户端原语的共同哲学:能力在服务器、权力在客户端);
  5. TypeScript 版:@modelcontextprotocol/sdk,McpServer + registerTool,结构与本文一一对应;
  6. 发布:打包成 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 开发者”。下一步建议:挑一个你每天重复做的手工操作(查某个内部系统、整理某类文件),把它做成第二个工具。