MCP 协议实战：手把手教你用 Python 开发第一个 MCP Server

结论先行

开发第一个 MCP Server，Python SDK 只需要 15 行代码。

2026 年 7 月 28 日，MCP 发布第五版规范，MCP 月 SDK 下载量突破 4 亿次，成为连接 AI Agent 与外部工具的行业标准。这意味着现在开发 MCP Server，是在一个正在爆发的生态里卡位。

本文将带你从零开始，用 Python 开发一个可用的 MCP Server，并验证它能否被 MCP 客户端正常调用。

一、MCP 是什么

MCP（Model Context Protocol）是 Anthropic 推出的开放协议，让 AI 能用一种标准方式调用你的工具、读取你的数据。

打个比方：如果没有 MCP，每个 AI 应用都要为接入你的工具写一套专属代码；有了 MCP，你写一个 Server，所有 MCP 客户端（Claude、Cursor、VS Code Copilot 等）都能用。

二、环境准备

安装 Python SDK

推荐用 uv 管理项目，也可以用 pip：

# 推荐方式（uv）
uv init mcp-server-demo
cd mcp-server-demo
uv add "mcp[cli]"

# 或者直接用 pip
pip install "mcp[cli]"

需要 Python 3.10+。

三、15 行代码，一个完整的 MCP Server

创建一个 server.py：

from mcp.server import MCPServer

mcp = MCPServer("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:
"""Greet someone by name."""
return f"Hello, {name}!"

这就是一个完整的 MCP Server：一个工具（add），一个资源（greeting）。

你没写的东西比你写的更多：

• 没有 JSON Schema：a: int, b: int 就是 schema
• 没有请求解析：SDK 自动处理 JSON-RPC 消息
• 没有验证代码：类型注解自动校验参数
• 没有协议处理：生命周期、握手全部由 SDK 管理

代码解读

四、运行与测试

方式一：MCP Inspector（推荐）

MCP Inspector 是官方提供的可视化调试工具，最直观：

# 启动你的 Server
uv run mcp dev server.py

这会自动启动 Inspector 并连接你的 Server。在浏览器中打开后，可以直接测试 add 工具：

输入 a=1, b=2，返回 3。第一个 MCP Server 跑通了。

方式二：命令行直接运行

# Streamable HTTP 传输（适合部署）
uv run mcp run server.py –transport streamable-http

# 或 stdio 传输（适合本地集成）
uv run mcp run server.py

五、进阶：让 Server 真正有用

上面的 add 工具只是演示。一个真正有用的 MCP Server，需要处理实际业务逻辑。

示例：数据库查询工具

import sqlite3
from mcp.server import MCPServer

mcp = MCPServer("SQLite Explorer")

@mcp.resource("schema://main")
def get_schema() –> str:
"""Provide the database schema as a resource"""
conn = sqlite3.connect("database.db")
schema = conn.execute(
"SELECT sql FROM sqlite_master WHERE type='table'"
).fetchall()
return "\\n".join(sql[0] for sql in schema if sql[0])

@mcp.tool()
def query_data(sql: str) –> str:
"""Execute SQL queries safely"""
conn = sqlite3.connect("database.db")
try:
result = conn.execute(sql).fetchall()
return "\\n".join(str(row) for row in result)
except Exception as e:
return f"Error: {str(e)}"

这个 Server 让 AI 能够读取数据库结构、执行查询——这才是 MCP 的真正价值。

关键设计原则

六、常见踩坑

坑 1：ModuleNotFoundError: No module named 'mcp_server'

原因：没有在虚拟环境中运行。

解决：确保 uv run 或激活 venv 后再执行。

坑 2：MCP 客户端报“服务器启动失败”

原因：客户端配置的路径或 cwd 不对。

解决：先用命令行单独运行 Server，确认能启动后，再检查客户端的启动配置。

坑 3：工具调用超时

原因：某些工具首次执行需要初始化（如数据库连接）。

解决：在 Client 端增加 read_timeout_seconds，或把初始化逻辑移到 lifespan 中。

坑 4：Connection refused / 404

原因：Server 没启动，或路径写错了。

解决：先 curl 测试端点是否可达。Python FastMCP 独立运行时的默认路径通常是 /mcp。

七、总结

开发第一个 MCP Server 的核心就三步：

MCP 正在从“有状态”全面转向“无状态”核心，这意味着 MCP Server 可以部署在 Serverless 架构上，扩展性大幅提升。现在入门，时机正好。

参考：MCP Python SDK 官方文档 ，MCP 2026-07-28 规范变更 。