MCP服务搭建流程实战：用fastmcp在Claude Desktop跑通第一个Python工具

1. 从零理解 MCP 服务搭建fastmcp 到底解决了什么问题如果你最近在折腾 Claude Desktop大概率会看到一个词反复出现MCP。它的全称是 Model Context Protocol简单说就是一套让大模型能调用外部工具的通信规范。以前你想让 Claude 读一个本地文件只能手动复制粘贴有了 MCP 之后Claude 可以自己决定去调用你写的工具函数把结果拿回来继续推理。而 fastmcp 是这套协议在 Python 生态里最省心的实现。它把协议层的握手、序列化、stdio 通信全部封装掉你只需要写普通的 Python 函数加一个装饰器就能变成一个 Claude Desktop 能识别的工具。对于零基础读者来说这意味着你不需要理解 JSON-RPC 的报文格式也不需要手写 schema专注在业务逻辑上就行。这篇内容面向的是完全没接触过 MCP 的人。我会带你从环境准备开始写一个能列出目录、读取文件的 Python 工具服务然后配置到 Claude Desktop 里最后用真实对话验证它被正确调用。整个过程你都可以直接复制粘贴遇到报错我也会把排查路径写清楚。先明确一下我们要做的东西一个本地运行的 Python 脚本通过 stdio 和 Claude Desktop 通信对外暴露两个工具——list_directory和read_file。Claude 在对话中判断需要读文件时会自动调用这两个函数。你不需要开端口不需要部署服务器一切都在本机完成。在开始之前你需要确认三件事本机装了 Python 3.10 或更高版本、装了 Claude Desktop 客户端、有一个能编辑文本的编辑器。Python 版本很关键fastmcp 依赖的一些类型注解特性在 3.9 以下会报错。你可以用python --version确认一下。我试过在 Windows 和 macOS 上各跑一遍流程基本一致差异主要在配置文件路径和 Python 可执行文件的写法上。下面我会把两个系统的差异都标出来你按自己的系统对号入座即可。2. TaoToken 前置准备给 MCP 工具接上模型能力在正式写 MCP 服务之前有一个容易被忽略的前置环节你的 Claude Desktop 本身需要能正常调用模型。如果你用的是官方客户端并且已经登录这一步可以跳过但如果你希望通过 API 的方式接入或者想在自己的脚本里测试工具逻辑就需要先准备好模型访问凭证。TaoToken 在这里的角色是提供统一的模型接入入口。它的 API 地址是https://taotoken.net/api你可以在控制台里创建 API Key然后用在支持自定义 Base URL 的客户端里。对于 MCP 场景来说这个前置准备的意义在于当你想脱离 Claude Desktop 单独调试工具函数时可以用一个最小的 Python 脚本来模拟模型调用确认工具返回的数据格式是对的。具体操作上你先访问控制台创建一个 Key然后在需要的地方填入三件套Base URL、API Key、Model ID。Base URL 填https://taotoken.net/apiModel ID 根据你实际要用的模型填写。如果你只是想让 Claude Desktop 调用本地 MCP 工具这一步不是必须的因为 Claude Desktop 自己会处理模型调用但如果你打算写自动化脚本或者做批量测试提前把 Key 准备好会省很多事。这里要提醒一点MCP 服务和模型 API 是两回事。MCP 服务负责“提供工具”模型负责“决定调用哪个工具”。两者通过 Claude Desktop 这个宿主连接起来。所以你在配置 MCP 的时候不需要在 MCP 脚本里写任何 API KeyKey 是给宿主或者你自己的测试脚本用的。如果你后续想用 Coding Plan 来做长期的编码辅助或者想把 MCP 工具接入到自己的 Agent 流程里可以先把 Key 创建好放着。接入文档里有不同客户端的配置示例包括 Claude Code、Cline 这些你可以对照着看。模型对话页面也可以直接测试 Key 是否可用省得在配置文件里反复试错。3. 可复制配置fastmcp 服务模板与 Claude Desktop 接入片段这一节是核心我会给出完整的文件结构和配置内容。你新建一个文件夹比如叫mcp-demo在里面创建两个文件requirements.txt和file_server.py。先看依赖文件。内容很简单一行就够fastmcp0.1.0然后在终端里执行安装pip install -r requirements.txt如果你用的是虚拟环境先激活再装。装完之后可以用pip show fastmcp确认版本。接下来是服务端代码。我把完整内容贴出来你可以直接复制到file_server.py#!/usr/bin/env python3 import sys import io sys.stdout io.TextIOWrapper(sys.stdout.buffer, encodingutf-8) from mcp.server.fastmcp import FastMCP import os from pathlib import Path mcp FastMCP(文件系统管理器) mcp.tool() def list_directory(path: str .) - str: target_path Path(path) if os.path.isabs(path) else Path.home() / path if not target_path.is_dir(): return 错误路径不存在或不是目录 items [f.name for f in target_path.iterdir()] return f目录 {target_path} 中的内容\n \n.join(items) mcp.tool() def read_file(file_path: str) - str: path Path(file_path) if not path.is_file(): return 错误文件不存在 try: with open(path, r, encodingutf-8) as f: return f.read() except Exception as e: return f读取文件出错{e} if __name__ __main__: mcp.run(transportstdio)这段代码做了三件事创建 MCP 实例、用mcp.tool()装饰器注册两个工具、以 stdio 模式启动服务。注意开头那三行强制 UTF-8 输出的代码这是为了避免 Windows 终端下 GBK 编码导致的崩溃后面排障部分会详细说。然后是 Claude Desktop 的配置文件。路径按系统区分macOS 是~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 是%APPDATA%\Claude\claude_desktop_config.jsonLinux 是~/.config/Claude/claude_desktop_config.json。配置内容如下你需要把路径替换成自己机器上的实际路径{ mcpServers: { file-server: { command: python3, args: [/你的完整路径/mcp-demo/file_server.py] } } }Windows 用户要注意两点command最好写 Python 的完整路径args里的反斜杠要转义。比如{ mcpServers: { file-server: { command: C:\\Users\\YourName\\AppData\\Local\\Programs\\Python\\Python311\\python.exe, args: [C:\\Users\\YourName\\mcp-demo\\file_server.py] } } }保存配置文件后完全退出 Claude Desktop 再重新打开。不是关窗口是彻底退出进程。macOS 用 CmdQWindows 在任务栏右键退出。4. 验证请求与成功结果确认工具被正确识别和调用重启之后你怎么知道 MCP 服务加载成功了有两个验证点。第一个是看 Claude Desktop 的界面。在输入框附近通常会有一个工具图标或者连接状态提示不同版本位置不太一样。如果配置正确你会看到file-server出现在已连接的服务列表里。如果没看到先别急着改代码去日志里找原因。第二个是直接对话测试。在 Claude 里输入类似“请列出我主目录下的文件”或者“帮我读一下某个文件的内容”。如果 Claude 判断需要调用工具它会显示一个调用过程然后返回结果。这时候你看到的输出就是你的 Python 函数返回的字符串。为了更可控地验证你可以先手动跑一下服务脚本确认它本身不报错python file_server.py如果没有任何输出就停在那里说明服务正常启动了在等待 stdio 输入。按 CtrlC 退出即可。如果报错那就是代码或环境问题跟 Claude Desktop 无关先解决这个。另一个验证方式是用 MCP 的调试工具。fastmcp 自带一个开发模式你可以用mcp dev file_server.py启动一个带界面的调试器在里面直接调用工具、看输入输出。这个方式适合在接入 Claude Desktop 之前先把工具逻辑调通。当你确认脚本能跑、配置路径没错、Claude Desktop 也重启了就可以在对话里试。比如你问“列出我文档目录里的文件”Claude 可能会调用list_directory并传入Documents。如果返回的是目录内容列表说明整条链路通了。这里有个细节Claude 是否调用工具取决于它自己的判断。有时候它会直接回答而不调用这时候你可以更明确地说“请使用 file-server 工具列出目录”。多试几次就能感受到它的触发逻辑。5. 本篇常见错排查401、spawn ENOENT、编码崩溃怎么解搭建过程中最容易卡住的就是这几类报错。我按实际遇到的频率排一下。第一类是spawn python ENOENT。这个错误的意思是 Claude Desktop 找不到python命令。根源通常是 Python 装在了非标准路径或者你用的是 Microsoft Store 版本它的可执行文件藏在WindowsApps目录里不在系统 PATH 中。解决办法是先找到完整路径where python或者where python3把输出的完整路径复制出来填到配置文件的command字段里。注意 Windows 路径要双反斜杠转义。改完保存彻底重启 Claude Desktop。第二类是编码错误导致的崩溃报错信息类似UnicodeEncodeError: gbk codec cant encode character。这是因为 Windows 终端默认用 GBK 编码而你的脚本里如果有 emoji 或者特殊字符print 的时候就会炸。解决办法有两个一是删掉所有 print 里的 emoji用[OK]这种纯 ASCII 替代二是在脚本开头强制标准输出用 UTF-8就是我上面模板里那三行。推荐第二种一劳永逸。第三类是 401 或者认证失败。如果你在 MCP 脚本里调用了外部 API并且把 Key 写错了或者没传就会看到 401。注意 MCP 工具本身不需要 Key但如果你在工具函数里发 HTTP 请求那就要确保 Key 正确。检查一下 Base URL 是不是https://taotoken.net/apiKey 有没有多余空格。第四类是reading choices相关的解析错误。这种通常出现在你用了某个客户端去调模型但返回格式不符合预期。如果你是用 Claude Code 或者 Cline 这类工具接入检查一下 Model ID 有没有填对以及 Base URL 后面有没有多写斜杠。三件套——Base URL、Key、Model ID——任何一个不对都会导致解析失败。第五类是 OAuth 相关的报错。如果你在配置里启用了某些需要 OAuth 的远程服务但本地没配好回调就会卡在授权环节。对于本篇的本地 stdio 服务来说不涉及 OAuth所以如果你看到这类错误大概率是配置文件里混入了其他服务的配置检查一下mcpServers下面是不是只有你自己的服务。排查的时候有一个通用思路先单独跑 Python 脚本确认脚本本身没问题再检查配置文件路径和转义最后看 Claude Desktop 的日志。日志位置在配置目录旁边macOS 是~/Library/Logs/Claude/Windows 在%APPDATA%\Claude\logs\。日志里会明确告诉你哪个服务启动失败、报了什么错。6. 从本地工具到长期编码流把 MCP 接入你的日常工作跑通第一个工具之后你可以沿着这个模板继续扩展。比如加一个write_file工具让 Claude 能帮你写文件或者加一个search_code工具在指定目录里做关键词搜索。fastmcp 的装饰器模式让扩展变得很简单你只需要定义新函数加上mcp.tool()重启服务就生效。如果你打算把 MCP 用在长期的编码辅助场景里比如让 Claude 帮你读项目文件、改代码、跑测试那可以考虑把模型接入也统一管理起来。TaoToken 的 Coding Plan 就是为这种场景准备的你可以在控制台里创建 Key然后配置到 Claude Code 或者 Cline 里配合本地 MCP 工具一起用。接入文档里有完整的配置示例包括settings.json和auth.json的写法。对于需要频繁调试的场景建议把 MCP 服务的日志输出到一个文件里方便回溯。你可以在mcp.run()之前加一些文件日志的配置把每次工具调用的入参和返回都记下来。这样当 Claude 调用结果不符合预期时你能快速定位是工具逻辑问题还是模型理解问题。另外一个小技巧工具函数的返回值尽量用结构化文本比如 JSON 字符串或者带明确分隔符的列表。这样模型在解析的时候不容易出错。如果你返回的是自然语言描述模型有时候会过度解读。我在list_directory里用换行分隔文件名就是出于这个考虑。最后如果你想让多个 MCP 服务同时运行比如一个管文件、一个管数据库只需要在claude_desktop_config.json的mcpServers下面加多个条目每个条目指向不同的脚本。Claude Desktop 会分别启动它们模型在需要的时候自动选择调用哪个。注意每个服务的名字要唯一不要重复。整套流程走下来你会发现 MCP 的门槛比想象中低。核心就是写 Python 函数、配 JSON、重启客户端。真正花时间的地方在排错而排错的关键是学会看日志和单独测试脚本。把这两件事做好后面加多少工具都只是重复劳动。