就学joinlearn.com
AI 工具教程12 分钟

手把手开发你的第一个 MCP Server:Python/FastMCP 给 AI 接自定义工具(2026)

mcp server 开发完整教程:用 Python + FastMCP 从零写一个能调外部 API 的 MCP server,本地用 MCP Inspector 调试,再接进 Claude Code。含实测代码、调试日志、踩坑与大陆可用性。

d
dfkai
作者
MCPFastMCPPythonMCP ServerClaude CodeMCP Inspector

我为什么自己写了一个 MCP Server

mcp server 开发说白了就一句话:把你自己的脚本、内网 API、私有数据库,包装成 AI 能直接调用的"工具"。这篇 fastmcp 教程带你用 python 写 mcp,从装环境、写第一个 tool、用 MCP Inspector 调试,一路接进 Claude Code。

TL;DR:pip install fastmcp → 用 @mcp.tool 装饰一个普通 Python 函数 → fastmcp dev 起 MCP Inspector 点点点调通 → fastmcp install claude-code server.py 一键挂进 Claude Code。我实测从空文件夹到 Claude Code 里能用,大概 20 分钟。

先说背景。如果你还不知道 MCP 是什么、scope 怎么分、stdio 和 HTTP 传输有啥区别,建议先看我那篇MCP 入门 + Claude Code 配置指南,这篇默认你已经会用别人的 MCP server 了,我们这次是自己造一个。

2025 年 12 月 MCP 被捐给了 Linux 基金会下的 Agentic AI Foundation,成了跨工具的通用层(Anthropic 官方说明)。这意味着你今天写的一个 MCP server,Claude Code、Cursor、Gemini 甚至别家客户端都能直接用——一次开发,到处接。对我这种同时用好几个 AI 工具的人来说,这是自建 MCP 最大的动机。

我个人真正动手写第一个 MCP 的契机,是想让 Claude Code 直接查我自己维护的一个加密货币行情接口。复制粘贴 JSON 太蠢了,不如把它变成 AI 能自己调的工具。下面就用这个真实小项目走一遍全流程。

什么时候该自己造,什么时候别折腾

不是所有需求都值得自己写 MCP。我的判断标准:

场景要不要自建 MCP说明
内网 API / 私有数据库强烈建议官方 server 不可能覆盖你的私有系统
把一段常用 Python 脚本给 AI 调建议比每次贴代码靠谱
公网知名服务(GitHub、Slack)不建议直接用官方/社区现成 server
一次性任务不必直接让 AI 写脚本跑一遍就行

简单讲:当 AI 需要反复访问"只有你有"的东西时,才值得封装成 MCP。 想系统看看 MCP 在真实项目里怎么和 Agent 配合,我把整套实战拆在了用 AI Agent 从零做一个真实项目里,那是这一批文章的总纲。

装 FastMCP:2026 年的主流姿势

为什么是 FastMCP?官方 MCP 也有 Python SDK,但 FastMCP 用一个 @mcp.tool 装饰器就搞定 schema、参数校验、文档生成,几乎是零样板代码。截至我写稿时(2026-05),最新版是 FastMCP 3.3.1(2026-05-15 发布),FastMCP 3.0 在 2026-01-19 落地,带来了组件版本化、细粒度授权、OpenTelemetry 等(PyPI 页面 / 官方文档)。要求 Python ≥ 3.10,我自己用的是 py312 conda 环境。

我推荐用 uv(更快),没装 uv 用 pip 也一样:

# 推荐:uv
uv pip install fastmcp

# 或者 pip(我大陆环境会加清华镜像,见后文踩坑)
pip install fastmcp

# 验证版本
python -c "import fastmcp; print(fastmcp.__version__)"
# 实测输出(以你环境为准):3.3.1

写第一个 tool:30 秒能跑起来的最小版

先来个官方风格的最小例子,确认环境通了。新建 my_server.py:

from fastmcp import FastMCP

mcp = FastMCP("My MCP Server")

@mcp.tool
def greet(name: str) -> str:
    """跟某人打招呼"""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run()   # 默认 stdio 传输

就这么多。@mcp.tool 会自动读取函数签名(name: str)生成 JSON schema,读取 docstring 当工具描述给 AI 看。所以类型标注和 docstring 不是可选项,是给 AI 看的说明书——这是我踩过的第一个坑,后面细说。

直接跑 python my_server.py 它会以 stdio 模式等待 MCP 客户端连接,光看终端没反应是正常的(stdio 就是给程序对程序说话用的)。

FastMCP 开发到接入 Claude Code 的完整流程

来个真的:封装一个外部 API 工具

greet 没意义,我们写点实战的。下面是我那个查行情的 server 的简化版——封装一个真实可调的公开接口(CoinGecko 风格),让 AI 能查币价。重点看注释里我标的几个关键点:

# crypto_server.py
import httpx
from fastmcp import FastMCP

mcp = FastMCP("Crypto Price Server")

API_BASE = "https://api.coingecko.com/api/v3"

@mcp.tool
def get_price(coin_id: str, vs_currency: str = "usd") -> dict:
    """查询某个加密货币的当前价格。

    Args:
        coin_id: 币种 ID,如 bitcoin、ethereum、solana(用 CoinGecko 的 id)
        vs_currency: 计价货币,默认 usd,也可填 cny
    """
    resp = httpx.get(
        f"{API_BASE}/simple/price",
        params={"ids": coin_id, "vs_currencies": vs_currency},
        timeout=10,
    )
    resp.raise_for_status()
    data = resp.json()
    if coin_id not in data:
        # 把错误也讲清楚,AI 才能自我纠正
        return {"error": f"找不到币种 {coin_id},请确认是 CoinGecko 的 id"}
    return {"coin": coin_id, "currency": vs_currency, "price": data[coin_id][vs_currency]}

@mcp.tool
def list_trending() -> list[str]:
    """获取当前 CoinGecko 上的热门搜索币种列表。"""
    resp = httpx.get(f"{API_BASE}/search/trending", timeout=10)
    resp.raise_for_status()
    return [c["item"]["id"] for c in resp.json().get("coins", [])]

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

我从这个真实例子里总结的三条经验:

  1. docstring 要写给 AI,不是给同事。 coin_id 我特意补了"用 CoinGecko 的 id",否则 AI 会传 BTC 而接口要的是 bitcoin,直接报错。
  2. 返回值结构化。 返回 dict/list 比返回一坨字符串好,AI 解析更稳。
  3. 错误信息要可读。 上面"找不到币种"那行,我实测能让 Claude 自己改参数重试,而不是把红色异常糊给用户。

别忘了 pip install httpx。

本地调试:MCP Inspector 是你的 Postman

代码写完别急着接 Claude Code,先用 MCP Inspector 在浏览器里点通。MCP Inspector 是官方的可视化调试工具,相当于 MCP 世界的 Postman——它启动你的 server,列出所有 tool/resource/prompt,让你手动填参数调用,并把底层 JSON-RPC 报文全摊给你看(官方文档)。

FastMCP 把它包进了 fastmcp dev,一条命令搞定:

fastmcp dev crypto_server.py

或者直接用官方 Inspector 启动 Python server:

npx @modelcontextprotocol/inspector uv run --with fastmcp fastmcp run crypto_server.py

我第一次跑的时候,终端大概是这样(实测示意,以你环境为准):

Starting MCP inspector...
⚙️  Proxy server listening on 127.0.0.1:6277
🔑  Session token: 7f3a9c2e8b...  (打开链接时自动带上)
🔗  http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=7f3a9c2e8b...
🚀  MCP Inspector is up and running. Open the link above.

注意那个 Session token:Inspector 默认要鉴权,启动时随机生成一个 token,直接点终端给的带 token 的链接就行,手动开 localhost:6274 会连不上——这是新手最常卡住的地方。

进到浏览器界面后,我的调试动作是这样的:

  1. 左边 Server connection pane:确认 transport 选 stdio,点 Connect,左下能看到 capability 协商成功。
  2. 切到 Tools 标签:能看到 get_price 和 list_trending 两个工具,以及自动生成的参数表单。
  3. 在 get_price 表单里填 coin_id=bitcoin,点 Run。右侧立刻返回 {"coin":"bitcoin","currency":"usd","price":...},同时 Notifications/日志面板里能看到完整的 JSON-RPC 请求和响应。
  4. 故意填个 coin_id=BTC 试错误路径,确认我那条中文错误提示能正常返回。

我的工作流是:改代码 → 在 Inspector 点 Reconnect → 重测受影响的工具。 别每次都去重启 Claude Code 试,那太慢了。Inspector 这一步能把 90% 的 bug 在接入 AI 之前就拍死。

MCP Inspector 调试三步:连接 → 选工具填参 → 看 JSON-RPC 报文

接进 Claude Code:一条命令挂上去

Inspector 里调通了,接 Claude Code 就很轻松。FastMCP 自带安装命令(最省心):

# 一键安装,自动写好配置
fastmcp install claude-code crypto_server.py

# 如果一个文件里有多个 mcp 对象,显式指定
fastmcp install claude-code crypto_server.py:mcp

# 带额外依赖一起声明(很重要,见踩坑)
fastmcp install claude-code crypto_server.py --with httpx

如果你想手动控制,也可以用 Claude Code 原生命令(细节见MCP 入门篇讲的 scope):

# scope 默认 local(只当前项目),可换 user / project
claude mcp add crypto -- uv run --with fastmcp --with httpx fastmcp run crypto_server.py

# 带环境变量(比如 API key)
claude mcp add crypto -e API_KEY=xxx -- uv run --with fastmcp --with httpx fastmcp run crypto_server.py

Windows 用户注意:命令前要包一层 cmd /c,否则起不来,例如 claude mcp add crypto -- cmd /c uv run ...。这是 Windows 上 stdio server 的老坑了。

挂好后在 Claude Code 里 /mcp 能看到 crypto 已连接。我实测直接问"现在比特币多少钱(用人民币)",Claude 会自己调 get_price(coin_id="bitcoin", vs_currency="cny") 然后把结果讲给我——整个过程不用我贴任何 JSON。想把这种自定义工具和 subagent、skill 串起来,可以接着看Claude Code 完整教程。

部署与进阶:从本地脚本到内网可达

本地 stdio 够用,但如果要给团队或远程 Agent 用,有几件事得想清楚:

stdio vs HTTP。 本地、单机用 stdio(默认,零配置);要远程/多客户端访问,改用 Streamable HTTP:

if __name__ == "__main__":
    mcp.run(transport="http", host="0.0.0.0", port=8000)

或 CLI:fastmcp run crypto_server.py:mcp --transport http --port 8000。

内网 API 别裸奔到公网。 2026-05 在 Code with Claude London 上,Anthropic 给 Claude Managed Agents 放出了两个相关能力:Self-hosted Sandboxes(公测中) 让工具在你自己的基础设施里执行;MCP Tunnels(研究预览) 让 Agent 通过一个只往外拨的加密通道访问你私网里的 MCP server,不用开任何入站防火墙端口、不暴露公网地址(Anthropic 官方 / The New Stack 报道)。如果你的 MCP 要连内部数据库,优先走这条路,别图省事开公网。这两个功能状态会变,以官方最新为准。

部署清单(我自己的 checklist):

检查项为什么
--with 声明所有依赖不声明 httpx,远程跑必然 ImportError
给所有 tool 写类型 + docstringAI 调不对参数的根源
错误返回可读字符串AI 才能自我纠错重试
给外部请求加 timeout防止 server 卡死拖垮 Agent
敏感 key 走环境变量别硬编码进代码

中文环境踩坑实录

几个我在大陆环境实打实遇到的问题:

  • pip 装 fastmcp 慢/超时:加镜像 pip install fastmcp -i https://pypi.tuna.tsinghua.edu.cn/simple。uv 也可以配 UV_INDEX_URL 指向清华源。
  • fastmcp install 报找不到依赖:十有八九是忘了 --with httpx 这类。FastMCP 在隔离环境里跑 server,你 pip install 过的它不一定看得到,依赖要在命令里显式声明。
  • npx 拉 MCP Inspector 卡住:npm config set registry https://registry.npmmirror.com 换淘宝源,或者干脆用 fastmcp dev 让 FastMCP 帮你拉。
  • CoinGecko 这类公网 API 偶尔抽风:加 timeout + 重试,或换国产数据源。如果 server 内部要调 LLM,DeepSeek 这类国产模型的 API 在大陆更稳、也更便宜。

成本参考(实测示意,以你环境为准):FastMCP 本身免费开源,server 跑在你自己机器/服务器上;真正的开销是 server 里调的外部服务。我那个行情 server 用公开免费档接口,token 成本为 0;若 server 内部还要调大模型,折人民币的成本就看你接哪家——这也是我更愿意在 server 内部用国产模型的原因之一。

写在最后

MCP server 开发没你想的那么玄:一个普通 Python 函数 + 一个 @mcp.tool 装饰器 + FastMCP,就能给任意 AI 工具接上你的私有能力。我的建议是按"先 Inspector 调通、再接 Claude Code、最后才考虑远程部署"的顺序来,别一上来就折腾 HTTP 和隧道。

想看这个自建工具怎么嵌进一个完整的 Agent 项目里、怎么和上下文工程、RAG 配合,继续读这批的支柱文用 AI Agent 从零做一个真实项目;还没搞懂 MCP 基础的回去补MCP 入门 + Claude Code 配置。

想系统学 AI 工具与 Agent 开发?我的实战课程在这里:点此了解并立即订阅 →

FAQ

Q1:FastMCP 和官方 MCP Python SDK 是什么关系?要装哪个? FastMCP 是社区主导、最流行的高层框架,用装饰器极大简化了开发;官方 SDK 更底层。绝大多数人(包括我)直接用 FastMCP 就够了,pip install fastmcp 即可,截至 2026-05 最新是 3.3.1。

Q2:不用 Claude Code,能在 Cursor 或别的工具里用我写的 MCP 吗? 能。MCP 是通用标准(已在 Linux 基金会下治理),同一个 server 可以接 Claude Code、Cursor、Gemini 等。FastMCP 的 fastmcp install 也支持多种客户端。想对比这些工具差异看AI 编码 Agent 横评。

Q3:MCP Inspector 打不开/连不上怎么办? 最常见原因是没用终端打印的那条带 Session token 的链接。直接点终端里的 http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=... 链接,别手动敲地址。其次检查 server 是否报错退出了。

Q4:我的 MCP server 要连公司内网数据库,怎么安全暴露给云端 Agent? 别裸暴露到公网。用 Anthropic 2026-05 推出的 MCP Tunnels(研究预览)走只出站的加密隧道,或自托管 Sandbox 让工具在你自己环境里执行。具体能力和限制以官方最新文档为准。

喵

返回博客列表
分享文章：

相关文章

AI 工具教程

MCP 是什么 + Claude Code 配置 MCP 服务器完整指南(2026 入门)

MCP 是什么?一句话:AI 的 USB-C 接口。本文用第一人称实测带你搞懂 Model Context Protocol 中文含义、为何重要,并手把手用 claude mcp add 给 Claude Code 配置 MCP 服务器,附 stdio/Streamable HTTP、local/project/user scope、Windows cmd /c 踩坑全记录。

12 分钟
AI 工具教程

用 AI 编程 Agent 从零做一个真实小项目:2026 端到端实战(不会编程也能做软件)

我用 AI 编程 Agent 从需求到上线做了一个真实小项目的全程实录:选工具、写需求、设计、AI 编码、调试、部署。不会编程也能做产品的 vibe coding 中文实战指南,含实测耗时与踩坑。

16 分钟

想要更深入的学习？

订阅我们的课程，获得完整的视频教程、源码资料和专属答疑支持

查看全部课程