1. 为什么我要用 FastMCP 写第一个 MCP Server如果你已经在用 Claude Desktop大概率遇到过这种尴尬想让 Claude 帮你查一下本地某个数据、算一段业务逻辑、读一个内部接口结果它只能干巴巴地告诉你「我无法访问外部资源」。MCPModel Context Protocol就是来解决这件事的——它给 LLM 装了一双手让模型能调用你写的工具函数、读取你定义的数据资源。而 FastMCP 是这套协议里对 Python 开发者最友好的框架。它把底层 JSON-RPC 通信、传输协议、生命周期管理全部封装掉你只需要写普通的 Python 函数加一个mcp.tool()装饰器就能变成一个 Claude 可以调用的工具。说白了它把「给 LLM 造工具」这件事从协议工程降级成了写业务函数。这篇教程面向的是已经装好 Claude Desktop、会一点 Python、但还没跑通过 MCP 的开发者。我会带你从零搭一个能算加法、能返回个性化问候的 MCP Server然后把它挂到 Claude Desktop 上最后用客户端代码验证调用链路真的通了。整个过程不需要你理解 MCP 的报文格式跟着敲就行。需要提前说明的是MCP Server 本身是本地进程Claude Desktop 通过配置去拉起它。所以你会看到两个关键动作一是写 server.py二是改 Claude Desktop 的 config 文件。这两步跑通你的第一个 MCP 工具就活了。2. 环境准备与 TaoToken 前置说明在动手写代码之前先把 Python 环境和依赖理清楚。FastMCP 官方推荐用 uv 做包管理它比 pip 快很多而且能自动处理虚拟环境。如果你还没装 uv一条命令搞定pip install uv然后建一个项目目录初始化环境并安装 fastmcpmkdir my-first-mcp cd my-first-mcp uv init uv add fastmcpuv add会自动创建.venv并把 fastmcp 写进pyproject.toml。装完之后激活虚拟环境Windows 和 macOS/Linux 命令不同# Windows .venv\Scripts\activate # macOS / Linux source .venv/bin/activate激活后你可以用python -c import fastmcp; print(fastmcp.__version__)确认装好了。这里插一句关于模型侧的准备。Claude Desktop 本身负责对话但如果你后续想在自己的 Python 程序里直接调 LLM 来做更复杂的 Agent 编排就需要一个稳定的模型 API 入口。我平时用 TaoToken 来统一管理这类调用它的 API 地址是https://taotoken.net/api兼容常见的 OpenAI 风格请求格式接入成本很低。你可以在控制台里生成 API Key然后在代码里通过base_url指向它即可。这一步不是跑通 MCP 的必需项但如果你打算把 MCP 工具接到自己的 LLM 应用里提前把 Key 准备好会省事很多。获取入口在控制台的 API Keys 页面文档里也有完整的接入示例。环境就绪后我们进入正题写 server.py。3. 可复制的 FastMCP 项目骨架新建一个server.py把下面这段完整代码贴进去。我加了详细注释你可以直接跑# server.py from fastmcp import FastMCP # 实例化 MCP 服务器名字会显示在 Claude Desktop 的工具列表里 mcp FastMCP(我的第一个MCP服务器) # 注册一个工具两数相加 mcp.tool() def add(a: int, b: int) - int: 将两个数字相加 return a b # 注册一个工具字符串反转演示非数值场景 mcp.tool() def reverse_text(text: str) - str: 把输入的文本倒序返回 return text[::-1] # 注册一个动态资源根据 URI 中的 name 返回问候语 mcp.resource(greeting://{name}) def get_greeting(name: str) - str: 获取个性化问候 return f你好{name}欢迎使用 FastMCP。 if __name__ __main__: mcp.run()这段代码里有三个核心概念我用大白话解释一下。mcp.tool()装饰的函数就是「工具」。Claude 在对话时如果判断需要算数它会自动调用add把参数以 JSON 形式传进来拿到返回值再组织成自然语言回复你。工具函数的类型注解a: int, b: int很重要FastMCP 会据此生成参数 schemaClaude 靠这个知道该传什么类型的值。mcp.resource(greeting://{name})定义的是「资源」。资源不是被模型主动调用的而是作为一种可读取的数据源存在。URI 里的{name}是模板参数客户端请求greeting://张三时FastMCP 会把name张三传进函数。资源适合放配置、文档、用户资料这类上下文数据。mcp.run()启动服务器。默认走 stdio 传输也就是通过标准输入输出和 Claude Desktop 通信。这也是为什么 Claude Desktop 能直接拉起本地脚本——它把 server.py 当子进程启动然后通过管道收发消息。写完先别急着装到 Claude我们用开发模式跑一下确认服务器本身没问题fastmcp run server.py如果终端没有报错、光标停住等待输入说明服务器正常启动了。按CtrlC退出即可。这一步能过滤掉大部分语法和导入错误。4. 接入 Claude Desktop 的 config 配置服务器能跑之后下一步是让 Claude Desktop 认识它。FastMCP 提供了install命令会自动帮你改配置文件fastmcp install server.py执行后它会找到 Claude Desktop 的配置目录把 server.py 注册进去。不同系统的配置文件位置不一样系统配置文件路径Windows%APPDATA%\Claude\claude_desktop_config.jsonmacOS~/Library/Application Support/Claude/claude_desktop_config.jsonLinux~/.config/Claude/claude_desktop_config.json如果你想手动改或者install没生效可以打开这个 JSON 文件在mcpServers字段下加一段。注意路径要写绝对路径Windows 下反斜杠要转义{ mcpServers: { my-first-mcp: { command: uv, args: [ --directory, C:\\Users\\你的用户名\\my-first-mcp, run, server.py ] } } }macOS 或 Linux 下路径换成/Users/你的用户名/my-first-mcp即可。这里用uv run而不是直接python是因为 uv 会自动激活项目虚拟环境避免 Claude Desktop 找不到 fastmcp 依赖。改完配置必须完全退出 Claude Desktop 再重启不是关窗口是右键托盘图标退出。重启后在对话框右下角或工具图标那里你应该能看到my-first-mcp以及它下面的add、reverse_text两个工具。如果没显示先检查 JSON 有没有语法错误——多一个逗号都会导致整个配置失效。5. 验证请求与成功结果配置生效后直接在 Claude Desktop 里用自然语言测试。输入帮我算一下 37 加 58 等于多少Claude 会识别出这需要调用add工具界面上会出现一个工具调用的小卡片显示传入参数{a: 37, b: 58}然后返回结果95。如果它直接心算回答了而没调工具你可以明确说「用 add 工具算」强制触发。再测资源。输入读取 greeting://李雷 这个资源Claude 会去请求这个 URI拿到「你好李雷欢迎使用 FastMCP。」并展示给你。资源读取在界面上通常显示为一次 resource 调用。除了在 Claude 里点我更推荐用客户端代码做一次程序化验证这样你能看到完整的请求响应结构排障时心里有底。新建client.py# client.py import asyncio from typing import cast from fastmcp import Client from mcp.types import TextContent, TextResourceContents async def main(): # 直接指向 server.pyFastMCP 会自动拉起它 async with Client(server.py) as client: # 调用 add 工具 result await client.call_tool(add, {a: 12, b: 30}) text_content cast(TextContent, result[0]) print(fadd 工具结果: {text_content.text}) # 读取 greeting 资源 resource await client.read_resource(greeting://韩梅梅) text_resource cast(TextResourceContents, resource[0]) print(fgreeting 资源结果: {text_resource.text}) if __name__ __main__: asyncio.run(main())运行python client.py你应该看到add 工具结果: 42 greeting 资源结果: 你好韩梅梅欢迎使用 FastMCP。这两行输出就是链路打通的铁证。工具调用走的是call_tool资源读取走的是read_resource返回的都是内容块列表所以要用cast取第一个元素的text字段。如果你拿到的是空列表说明工具名拼错了或者服务器没注册成功。6. 本篇常见错误排查跑不通的时候九成问题出在下面这几个地方我按踩坑频率排一下。工具在 Claude 里不显示。先确认 Claude Desktop 是彻底退出重启的不是最小化。然后检查 config JSON 的路径是不是绝对路径Windows 下C:\Users\...在 JSON 里必须写成C:\\Users\\...。还有一个隐蔽点如果你用uv run--directory参数必须指向包含pyproject.toml的项目根目录指到子文件夹会找不到环境。报错ModuleNotFoundError: No module named fastmcp。这是 Claude Desktop 启动子进程时用的 Python 环境不对。解决办法就是配置里用uv run而不是裸python让 uv 去激活项目虚拟环境。如果你坚持用 python就得把虚拟环境里解释器的绝对路径写进command。工具被调用但返回错误。多半是参数类型不匹配。FastMCP 会根据类型注解做校验如果你写def add(a: int, b: int)而 Claude 传了字符串37就会校验失败。确保注解和实际传入类型一致必要时在函数内部做一次转换。资源 URI 读不到。检查模板写法和请求写法是否一致。定义是greeting://{name}请求就得是greeting://张三不能写成greeting:///张三或者漏掉协议头。URI 模板是严格匹配的。改了 server.py 但 Claude 行为没变。MCP Server 是启动时加载的改完代码必须重启 Claude Desktop 才会重新拉起进程。开发阶段建议用fastmcp run server.py配合客户端脚本调试比反复重启 Claude 快得多。如果你在接入自己的 LLM 应用时遇到 API 调用层面的问题比如鉴权失败或 base_url 配错可以去 TaoToken 的接入文档对照一下请求格式那里有各语言的完整示例。API Key 在控制台的 API Keys 页面管理建议单独建一个 Key 用于 MCP 相关项目方便排查和轮换。7. 下一步把 MCP 接到你的编码工作流第一个 MCP 跑通之后你会发现真正的价值在于把重复劳动工具化。比如把团队的代码规范检查、数据库查询封装、内部 API 调用都做成 MCP 工具Claude 就能在对话里直接帮你执行而不是你复制粘贴来回倒腾。如果你打算长期用 MCP 做编码辅助和 Agent 编排可以考虑 TaoToken 的 Coding Plan它在调用额度和并发上更适合这种持续性的工具调用场景配合 MCP 做多轮任务会比较顺。模型对话能力可以在模型对话页面直接体验确认工具调用和上下文理解是否符合预期。接入相关的 Key 和文档入口分别是 API Keys 和接入文档按需取用即可。我自己的习惯是每做一个新工具先用client.py脚本验证一遍输入输出确认无误再挂到 Claude Desktop。这样出问题时能快速定位是工具逻辑的锅还是配置的锅。MCP 这东西跑通第一个之后后面就是复制骨架、换函数体的体力活了。