用 Python SDK 写第一个 MCP Server

用 Python SDK 写第一个 MCP Server

基础概念

如果你已经理解了 MCP 的三大原语，下一步最自然的问题就是：自己怎么写一个 Server？

官方给 Python 路线的答案很明确：优先用 Python SDK + FastMCP。它会帮你把协议层那些烦人的事先包掉，比如：

• 生命周期和握手
• 工具 schema 生成
• 资源和提示词注册
• stdio / HTTP 传输接线

也就是说，你的主要工作不再是“手搓 JSON-RPC”，而是把业务能力用 Python 函数表达出来。

这里有两个官方事实需要先说清：

1. MCP 官方 quickstart 明确要求 Python 3.10+
2. quickstart 明确要求 Python MCP SDK 1.2.0 或更高

我又查了 PyPI 当前元数据：截至 2026-04-11，mcp 包最新版本是 1.27.0，要求 Python >=3.10。

核心要素

从 Python 函数到 MCP Server 的链路

开发时你真正要关心的层次

对第一版服务器来说，FastMCP 几乎总是对的默认选项。

基础用法

第一步：创建项目

官方 quickstart 推荐先用 uv 初始化项目：

uv init weather
cd weather
uv venv
source .venv/bin/activate
uv add "mcp[cli]" httpx

如果你只是做最小本地 demo，不一定非要叫 weather，但安装思路就是这样。

第二步：写一个最小 Server

下面这个例子保留了官方 quickstart 和 Python SDK README 的核心结构，但缩成最适合入门理解的版本：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("demo")


@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b


@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Return a greeting resource."""
    return f"Hello, {name}!"


@mcp.prompt()
def review_prompt(topic: str) -> str:
    """Generate a simple review prompt."""
    return f"Please review the topic: {topic}"


if __name__ == "__main__":
    mcp.run()

这里最关键的不是代码长短，而是这三行装饰器分别在做什么：

• @mcp.tool()：注册“可执行动作”
• @mcp.resource()：注册“可读取数据”
• @mcp.prompt()：注册“可复用提示词模板”

第三步：本地开发调试

Python SDK README 里给的最快调试方式是：

uv run mcp dev server.py

如果你的 Server 依赖额外包，也可以直接在开发命令里临时带上：

uv run mcp dev server.py --with pandas --with numpy

这条命令背后做的事情可以简单理解成：

1. 启动你的 FastMCP Server
2. 自动接上 Inspector
3. 让你马上在浏览器里调 Tools / Resources / Prompts

这一点非常适合边写边试。

第四步：安装到 Claude Desktop

官方 README 里还提供了直接安装到 Claude Desktop 的方式：

uv run mcp install server.py

也支持：

uv run mcp install server.py --name "My Analytics Server"
uv run mcp install server.py -v API_KEY=abc123 -v DB_URL=postgres://...
uv run mcp install server.py -f .env

这比你手改 JSON 配置更省事，尤其在开发期非常舒服。

第五步：如果你要直接运行

Python SDK README 还给了 direct execution 的路线：

python server.py

或者：

uv run mcp run server.py

不过有个官方限制一定要记住：

uv run mcp run 和 uv run mcp dev 只支持 FastMCP，不支持 low-level server 变体。

第六步：什么时候切到 HTTP

如果你只是本地桌面客户端调试，stdio 已经够了。但 Python SDK README 也明确写了：生产部署更推荐 Streamable HTTP，并建议：

• stateless_http=True
• json_response=True

一个最小示意：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP(
    "StatelessServer",
    stateless_http=True,
    json_response=True,
)


@mcp.tool()
def hello(name: str = "World") -> str:
    """Say hello."""
    return f"Hello, {name}!"


if __name__ == "__main__":
    mcp.run(transport="streamable-http")

同类工具对比

“用 Python 写第一个 MCP Server”也有不同写法：

核心区别：

• FastMCP：先把功能做出来，最适合第一版。
• low-level server：当你需要更细的协议控制，再下沉。
• 手搓协议层：除非你在做 SDK 或特殊基础设施，否则不值得。

常见误区

优劣势分析

思考题

参考资料

1. MCP 官方 quickstart：Server Developer Guide：https://modelcontextprotocol.io/quickstart/server（查询日期 2026-04-11）
2. MCP Python SDK 官方仓库：https://github.com/modelcontextprotocol/python-sdk（查询日期 2026-04-11）
3. MCP Python SDK 文档站：https://modelcontextprotocol.github.io/python-sdk/（查询日期 2026-04-11）
4. PyPI mcp 包信息：https://pypi.org/project/mcp/（查询日期 2026-04-11）
5. MCP Python SDK 安装文档：https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/installation.md（查询日期 2026-04-11）
6. MCP Python SDK 测试文档：https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/testing.md（查询日期 2026-04-11）