1. 先搞清楚 MCP server 到底是个什么东西MCP 全称 Model Context Protocol你可以把它理解成 AI 客户端和外部工具之间的一根“标准数据线”。以前你想让 AI 读你电脑上的文件、查数据库、调接口得给每个客户端单独写一套插件现在只要写一个 MCP server任何支持 MCP 的客户端Cherry Studio、Trae、Claude Desktop 等都能直接连上来用。一个最小可用的 MCP server 其实就三件事声明自己叫什么名字、注册几个工具函数、启动一个通信通道。工具函数就是普通的 Python 函数加个mcp.tool()装饰器MCP 框架会自动读取函数签名和 docstring把它变成 AI 能调用的工具。通信通道目前最常用的是stdio标准输入输出适合本地进程和sseServer-Sent Events适合跨进程/远程。这篇教程面向完全没写过 MCP server 的读者从装环境开始一步步写出能跑通的代码最后用 TaoToken 的统一 Key 把模型调用接进来完成一次真实的“AI 调用我写的工具”的闭环。全程用 Windows PowerShell 演示macOS/Linux 把路径换一下就行。2. 前置准备Python 环境与 TaoToken 统一 Key2.1 用 uv 管理 Python 环境我推荐用uv来管 Python 版本和依赖它比 pip venv 快很多而且能自动帮你创建虚拟环境。打开 PowerShell粘贴下面这行powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex装完后如果提示uv不在 PATH 里按它给的提示执行一次$env:Path C:\Users\你的用户名\.local\bin;$env:Path然后确认版本uv --version uv python list选一个 3.11 以上的版本装上uv python install 3.11.132.2 拿到 TaoToken 的统一 KeyTaoToken 的作用是把多家模型的调用收敛到一个 API 通道和一个 Key 上你不用为每个模型单独配 base_url 和密钥。注册后进控制台创建 API Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteAPI Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建完把 Key 复制出来形如sk-xxxx。API 的基础地址是https://taotoken.net/api注意这个地址后面不加 UTM 参数直接用于代码里的base_url。后面第 4 节我们会用它发一次真实请求。3. 从零写一个 MCP server可复制的配置与代码3.1 初始化项目新建一个文件夹放你的 MCP servermkdir my-mcp-server cd my-mcp-server uv init . -p 3.11.13 uv add mcp[cli]uv init会生成pyproject.toml和main.pyuv add会把 MCP SDK 装进.venv虚拟环境。用 VS Code 或 Trae 打开这个文件夹编辑器会自动识别.venv。3.2 最小骨架一个工具 一个资源把main.py的内容替换成下面这段。这是 MCP 协议里“工具注册与调用”的最小骨架from mcp.server.fastmcp import FastMCP mcp FastMCP(Demo) mcp.tool() def add(a: int, b: int) - int: Add two numbers return a b mcp.resource(greeting://{name}) def get_greeting(name: str) - str: Get a personalized greeting return fHello, {name}! if __name__ __main__: mcp.run(transportstdio)几个关键点解释一下FastMCP(Demo)里的字符串是 server 名称客户端连接时会显示。mcp.tool()装饰的函数会被注册成工具AI 根据 docstring 判断什么时候调用它。mcp.resource()注册的是资源用 URI 模板访问适合返回只读数据。mcp.run(transportstdio)表示用标准输入输出通信客户端会以子进程方式启动这个脚本。3.3 加三个真实有用的工具光有加法没意思我们加三个操作桌面 txt 文件的工具这样能真正验证“AI 调用本地能力”import os from pathlib import Path from mcp.server.fastmcp import FastMCP mcp FastMCP(桌面 TXT 文件统计器) mcp.tool() def count_desktop_txt_files() - int: 统计桌面上 .txt 文件的数量 desktop_path Path(os.path.expanduser(~/Desktop)) txt_files list(desktop_path.glob(*.txt)) return len(txt_files) mcp.tool() def list_desktop_txt_files() - str: 获取桌面上所有 .txt 文件的列表 desktop_path Path(os.path.expanduser(~/Desktop)) txt_files list(desktop_path.glob(*.txt)) if not txt_files: return 桌面上没有找到 .txt 文件。 file_list \n.join([f- {file.name} for file in txt_files]) return f在桌面上找到 {len(txt_files)} 个 .txt 文件\n{file_list} mcp.tool() def read_txt_file(filename: str) - str: 读取指定txt文件的内容 Args: filename: txt文件的名称例如test.txt desktop_path Path(os.path.expanduser(~/Desktop)) file_path desktop_path / filename if not file_path.exists(): return f错误文件 {filename} 不存在于桌面上。 if file_path.suffix.lower() ! .txt: return f错误文件 {filename} 不是txt文件。 try: with open(file_path, r, encodingutf-8) as f: content f.read() return f文件 {filename} 的内容\n\n{content} except Exception as e: return f读取文件时发生错误{str(e)} if __name__ __main__: mcp.run(transportstdio)注意read_txt_file的 docstring 里写了Args:段MCP 框架会解析它告诉 AI 这个参数是文件名。参数类型标注filename: str也很重要AI 靠它决定传什么值。3.4 客户端配置stdio 与 sse 两种接法stdio 模式下客户端配置一般长这样以 Cherry Studio 为例Trae 类似{ mcpServers: { desktop-txt: { command: uv, args: [ --directory, C:\\path\\to\\my-mcp-server, run, main.py ] } } }如果你想让 server 常驻、多个客户端共享可以改用 sse 模式。把启动那行改成mcp.run(transportsse, host127.0.0.1, port8000)客户端配置改成 URL 形式{ mcpServers: { desktop-txt-sse: { url: http://127.0.0.1:8000/sse } } }先手动跑一次 server 确认不报错uv run main.pystdio 模式下终端会“卡住”不动这是正常的它在等客户端发消息。sse 模式下会打印监听地址。4. 用 TaoToken 统一 Key 完成一次真实工具调用4.1 为什么要在 MCP 场景里用 TaoTokenMCP server 本身只负责“提供工具”真正决定调不调、怎么调的是背后的模型。如果你在客户端里配了好几个模型每个都要单独填 Key 和 base_url很麻烦。TaoToken 把这件事收敛成一个 Key、一个 base_url客户端里所有模型都走同一个通道。4.2 用 Python 验证 API 通道在动手接客户端之前先用一段脚本确认你的 Key 和通道是通的from openai import OpenAI client OpenAI( api_keysk-你的TaoToken密钥, base_urlhttps://taotoken.net/api ) resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: user, content: 用一句话说明什么是 MCP 协议} ] ) print(resp.choices[0].message.content)跑之前先装依赖uv add openai uv run python test_api.py如果返回了一段关于 MCP 的解释说明 Key 和通道都没问题。模型名按你实际开通的填TaoToken 支持的模型列表可以在模型对话页查看https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite4.3 在客户端里把模型和 MCP 串起来以 Trae 为例先在设置里把模型 provider 配成 OpenAI 兼容模式配置项值Base URLhttps://taotoken.net/apiAPI Keysk-你的TaoToken密钥Model你开通的模型名然后在 MCP 配置里加上第 3.4 节的desktop-txt那段。重启客户端后在对话里问帮我看看桌面上有几个 txt 文件列出来。模型会先调用count_desktop_txt_files再调用list_desktop_txt_files把结果拼成自然语言返回。你会在客户端的工具调用面板里看到两次 tool call 记录这就是一次完整的“模型 → MCP server → 本地文件系统”链路。4.4 验证返回结果成功的标志有三个客户端工具列表里能看到count_desktop_txt_files等三个工具对话触发后工具调用面板出现记录返回内容里的文件数量和你在桌面实际看到的一致。如果数量对不上先检查~/Desktop路径在你的系统上是否解析正确Windows 中文系统桌面路径一般是C:\Users\你的用户名\Desktopexpanduser能正确处理。5. 本篇常见错误排查5.1 uv 命令找不到装完 uv 后新开一个 PowerShell 窗口或者手动执行$env:Path C:\Users\你的用户名\.local\bin;$env:Path。如果还不行检查.local\bin目录下有没有uv.exe。5.2 客户端连不上 serverstdio 模式下最常见的原因是--directory路径写错或者路径里有空格没转义。Windows 路径用双反斜杠\\。另外确认uv run main.py能手动跑通跑不通说明依赖没装好回到项目目录执行uv sync。5.3 工具注册了但 AI 不调用检查 docstring 是否清晰。AI 靠 docstring 判断工具用途如果写得太模糊比如只写“处理文件”模型可能不知道什么时候该用。参数类型标注也要写全filename: str比filename好得多。5.4 sse 模式端口被占用换一个端口比如port8765。如果客户端连的是http://127.0.0.1:8000/sseserver 端端口必须一致。sse 模式下 server 要先启动再启动客户端。5.5 API 请求返回 401 或 404401 一般是 Key 错了或没带Bearer前缀检查 Key 是否完整复制。404 多半是 base_url 写错确认是https://taotoken.net/api不要多加/v1之类的后缀。接入细节可以参考接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite5.6 读取文件报编码错误Windows 上有些 txt 是 GBK 编码用encodingutf-8会报错。可以在open里加errorsignore或者用chardet探测编码。生产环境建议显式处理编码异常返回友好提示而不是抛栈。6. 接下来怎么走从玩具到长期可用的编码助手上面这个 server 已经能跑通完整链路了但它还是个玩具。如果你想把它变成日常编码/Agent 工作流的一部分下一步是把它接到支持长期会话的编码计划里让模型在多轮对话中持续调用你的工具。TaoToken 的 Coding Plan 就是为这种场景准备的https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果你更想先验证模型本身的能力可以直接在模型对话页里试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite写 MCP server 这件事最难的不是代码是理解“工具注册 → 客户端发现 → 模型决策 → 调用回传”这条链路。一旦跑通一次后面加工具就是复制粘贴改 docstring 的事。我自己的习惯是每加一个工具就先手动uv run跑一遍确认函数本身没问题再去客户端里测模型调用这样排障时能快速定位是 server 的问题还是客户端配置的问题。