tutorial 15 min read 如何用 Python 构建 MCP 服务器（分步教程） 使用 FastMCP 用 Python 构建 MCP 服务器。涵盖工具、资源、提示词、MCP Inspector 测试，以及 Claude Code/Desktop/Cursor 配置。

William Wang · 2026年4月9日 William Wang — TokRepo & GEOScore AI 创始人，专注 AI 开发者工具和搜索可见性。

一句话答案 用 Python 构建 MCP Server 的最快路径是官方 FastMCP SDK：uv init + uv add mcp[cli]，用 @mcp.tool() 装饰器定义 Tool、@mcp.resource() 定义 Resource，用 MCP Inspector 本地测试，然后配置到 Claude Code 的 .mcp.json 即可。20 行代码就能跑起第一个 Server。 目录 前置条件 什么是 MCP？ 步骤 1 — 搭建环境 步骤 2 — 创建基础服务器 步骤 3 — 添加资源 步骤 4 — 完整示例：GitHub Stars 服务器 步骤 5 — 用 MCP Inspector 测试 步骤 6 — 配置到 Claude Code FAQ 下一步 学习如何使用官方 FastMCP SDK 用 Python 构建生产级 MCP 服务器，用 MCP Inspector 测试，并在 Claude Code、Claude Desktop 和 Cursor 中配置。 前置条件 Python 3.10+ uv 包管理器（推荐）或 pip 基本 Python 知识 什么是 MCP？ 模型上下文协议（MCP） 是 Anthropic 创建的开放标准，让你构建服务器向 LLM 应用暴露数据和功能。MCP 服务器提供三种能力： 工具（Tools） — LLM 可调用的函数 资源（Resources） — LLM 可访问的只读数据 提示词（Prompts） — 可复用的 LLM 交互模板 浏览 TokRepo 上的 MCP 服务器配置 查看已有资源。 步骤 1 — 搭建环境

curl -LsSf https://astral.sh/uv/install.sh | sh
uv init my-mcp-server && cd my-mcp-server
uv venv && source .venv/bin/activate
uv add "mcp[cli]"
touch server.py

步骤 2 — 创建基础服务器

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-first-server")

@mcp.tool()
def add(a: int, b: int) -> int:
 """将两个数字相加。"""
 return a + b

@mcp.tool()
def multiply(a: int, b: int) -> int:
 """将两个数字相乘。"""
 return a * b

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

FastMCP 利用 Python 类型提示和 docstring 自动生成工具 schema。 @mcp.tool() 装饰器注册 MCP 工具。 步骤 3 — 添加资源

@mcp.resource("config://app-settings")
def get_settings() -> str:
 """返回应用设置。"""
 return '{"theme": "dark", "language": "en"}'

步骤 4 — 完整示例：GitHub Stars 服务器

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("github-stars")

async def github_request(path: str) -> dict[str, Any] | None:
 async with httpx.AsyncClient() as client:
 try:
 response = await client.get(
 f"https://api.github.com{path}",
 headers={"Accept": "application/vnd.github.v3+json"},
 timeout=30.0
 )
 response.raise_for_status()
 return response.json()
 except Exception:
 return None

@mcp.tool()
async def get_repo_info(owner: str, repo: str) -> str:
 """获取 GitHub 仓库信息。"""
 data = await github_request(f"/repos/{owner}/{repo}")
 if not data:
 return "获取失败。"
 return f"仓库: {data['full_name']}\nStars: {data.get('stargazers_count', 0):,}"

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

步骤 5 — 用 MCP Inspector 测试

npx @modelcontextprotocol/inspector uv run server.py

在 http://localhost:6274 打开可视化调试界面。 步骤 6 — 配置到 Claude Code

claude mcp add --transport stdio my-server \
 -- uv --directory /absolute/path/to/my-mcp-server run server.py

或创建 .mcp.json ：

{
 "mcpServers": {
 "my-server": {
 "command": "uv",
 "args": ["--directory", "/path/to/server", "run", "server.py"]
 }
 }
}

重要 ：stdio 传输模式下 绝对不要用 print() ，会破坏 JSON-RPC 消息。用 print("msg", file=sys.stderr) 或 logging.info() 。 FAQ Q: MCP 需要什么 Python 版本？
A: Python 3.10+。SDK 当前版本 v1.27.0。 Q: 可以用 pip 代替 uv 吗？
A: 可以。 pip install "mcp[cli]" 即可。 下一步 用 TypeScript 构建 MCP 服务器 为你的 API 构建 MCP 服务器 TokRepo MCP 服务器合集 html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);} 常见问题 为什么要用 FastMCP 而不是 mcp 原生 SDK？ + FastMCP 是 mcp[cli] 的高层封装，用 Python 装饰器定义 Tool 和 Resource，代码量减少 60%。类型标注自动转成 JSON Schema，不用手写 inputSchema。官方推荐新项目直接用 FastMCP，原生 SDK 只在需要底层控制时才用。 MCP Inspector 怎么测试 Server？ + 安装 @modelcontextprotocol/inspector 后运行 npx @modelcontextprotocol/inspector python server.py，会打开一个 Web UI 展示所有 Tool、Resource 和 Prompt，可以手动调用每个接口验证返回值。比直接在 Claude Code 里调试快 10 倍。 Python MCP Server 如何配置到 Claude Code？ + 在 ~/.claude/settings.json 的 mcpServers 字段添加配置，command 设为 python 或 uv run，args 指向 server.py 路径。推荐用 uv run 而不是 python，可以自动管理虚拟环境依赖，不会污染全局 Python。 Tool、Resource、Prompt 三者该如何选择？ + Tool 是 LLM 主动调用的函数（有副作用或需要参数），Resource 是 LLM 读取的只读数据（像文件系统），Prompt 是可复用的模板（用户手动触发）。大部分场景 90% 是 Tool，Resource 用于列表类只读接口，Prompt 很少用。 uv 和 pip 哪个更适合 MCP 开发？ + 强烈推荐 uv。uv 比 pip 快 10-100 倍，自动管理 .venv 和 lockfile，官方 FastMCP 文档示例全部用 uv。pip 仍然可用但需要手动 venv activate，开发体验差很多。uv init 加 uv add mcp[cli] 是标准起手式。 ← 上一篇 如何为你的 API 构建 MCP 服务器 下一篇 → 如何用 TypeScript 构建 MCP 服务器（分步教程）