1. 从零跑通第一个 MCP 服务到底难在哪很多人第一次听到 MCP 服务这个词第一反应是「这不就是给大模型加个函数调用吗」。真动手时才发现卡住新手的从来不是概念而是环境Python 版本不对、虚拟环境没激活、SDK 装完 import 报错、AI 编程助手连不上本地进程。我见过太多人复制了一段服务端代码结果在编辑器里点半天工具列表始终是空的。MCP 全称 Model Context Protocol你可以把它理解成 AI 编程助手和本地能力之间的一根标准数据线。以前你想让助手读个文件、查个数据库、算个复杂公式得自己写插件、对接口现在只要按 MCP 协议暴露一个工具支持 MCP 的客户端就能自动发现并调用。它适合谁适合刚学完 Python 基础、想给 AI 助手加点「手脚」的零基础开发者也适合想快速验证一个工具想法的人。这篇教程聚焦本地可复现的最小示例从终端环境准备、Python SDK 安装到写一个只有加法功能的 MCP 服务再在 AI 编程助手里完成一次真实工具调用。全程不需要服务器、不需要公网地址一台笔记本就能跑。常用的 MCP 网站我也会整理在最后方便你后续查资料、找现成服务。需要提前说明的是MCP 生态更新很快SDK 接口和客户端配置界面可能随版本变化。我下面给的命令和代码都以当前主流版本为准你照着敲如果遇到差异优先看报错信息第五节专门列了常见坑。2. 前置准备终端环境与 TaoToken 接入配置动手写代码前先把两件事搞定一个顺手的终端一个能调用模型的 API 入口。终端决定你敲命令舒不舒服API 入口决定你的 AI 编程助手能不能真正跑起来。终端方面macOS 和 Linux 自带的 Terminal 就够用Windows 建议用 Windows Terminal 或者 Warp。Warp 内置了命令补全和 AI 提示对新手比较友好跨平台支持也全。你不需要为了这篇教程专门换终端用现有的就行重点是能正常执行 python、pip、mkdir 这些命令。模型接入这块我用的是 TaoToken 的 API 服务。它的作用是给 AI 编程助手提供一个统一的模型调用入口你拿到 Key 之后填进 Cline、Cursor 这类工具里就能让助手具备对话和工具调用能力。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带后面那串参数。具体操作分三步。第一步打开官网注册账号进入控制台。控制台入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后能看到你的账户信息和用量。第二步创建 API Key入口是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 点新建复制生成的 Key这串字符只显示一次丢了就得重建。第三步如果你用的是 Cline 或 Claude Code 这类工具把 Base URL 填成 https://taotoken.net/api Key 填刚复制的那串Model ID 按你实际想用的模型填比如 claude-sonnet 系列或 gpt 系列具体以控制台模型列表为准。这里有个细节要注意Base URL 和 API Key 是两回事别把 Key 填到 URL 里。另外如果你用的是 Claude Code它的配置方式略有不同需要设置环境变量或者写进 settings 文件接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的详细步骤。想先试试模型对话效果可以直接用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 这个页面不用装任何工具就能发消息。前置准备做完你应该手上有三样东西一个能用的终端、一个 TaoToken 的 API Key、一个装好的 AI 编程助手Cline、Cursor、Claude Code 任选。接下来进入正题开始写 MCP 服务。3. 可复制配置Python SDK 安装与服务端代码骨架这一节是全文的核心所有命令和代码都可以直接复制。我按「建目录 → 建虚拟环境 → 装依赖 → 写代码」的顺序来每一步都说明它在干什么避免你机械复制却不知道原理。先建项目目录并进入mkdir mcp-demo-share cd mcp-demo-share第一行新建一个名为 mcp-demo-share 的文件夹第二行进入这个文件夹。名字你可以换成自己的但后面配置路径时要对应改。接着创建 Python 虚拟环境。虚拟环境的作用是把当前项目的依赖和系统 Python 隔离开避免不同项目互相污染python -m venv myenvWindows 用户如果 python 命令不识别试试 py -m venv myenv。创建完成后激活它# macOS / Linux source myenv/bin/activate # Windows myenv\Scripts\activate激活成功的标志是终端提示符前面多了 (myenv) 字样。这一步很多人会漏结果 pip 装到了全局环境后面 import 找不到包。然后安装 MCP 的 Python SDKpip install mcp如果下载慢可以加国内镜像源比如 pip install mcp -i https://pypi.tuna.tsinghua.edu.cn/simple 。装完可以用 pip show mcp 确认版本。现在创建主程序文件 main.py写入下面这段代码#!/usr/bin/env python # -*- coding: utf-8 -*- from mcp.server.fastmcp import FastMCP # 创建 MCP 服务器实例名字叫 Demo mcp FastMCP(Demo) # 注册一个工具两数相加 mcp.tool() def add(a: int, b: int) - int: 两数相加 return a b if __name__ __main__: print(服务已启动) mcp.run()这段代码做了三件事导入 FastMCP 这个高层封装类用 mcp.tool() 装饰器把一个普通 Python 函数注册成 MCP 工具函数签名里的类型注解和 docstring 会被客户端读取用来告诉模型这个工具是干嘛的、参数是什么类型最后在main里调用 mcp.run() 启动服务默认走标准输入输出stdio通信。启动命令很简单python main.py看到「服务已启动」就说明进程跑起来了。注意stdio 模式下这个进程会一直挂着等客户端连接你在终端里直接跑它不会自己退出这是正常的。真正调用要靠 AI 编程助手去拉起它。如果你想让服务更规范一点可以加一个 pyproject.toml把依赖和入口写清楚[project] name mcp-demo-share version 0.1.0 dependencies [mcp] [project.scripts] mcp-demo main:mcp.run这样以后可以用 mcp-demo 命令启动不用每次敲 python main.py。不过对第一个示例来说直接跑 main.py 最直观pyproject.toml 属于进阶用法你了解即可。代码写完后建议先在终端单独验证一次进程能不能正常启动确认没有语法错误和 import 错误再去配客户端。顺序反了的话客户端报错你分不清是代码问题还是配置问题。4. 验证请求在 AI 编程助手中完成一次工具调用服务端代码跑通只是第一步真正的验证是让 AI 编程助手发现这个工具并调用它。我以 Cline 为例Cursor 和 Claude Code 思路类似配置字段略有差异。打开 VS Code安装 Cline 插件然后在插件设置里填入 TaoToken 的 Base URL 和 API Key。Base URL 填 https://taotoken.net/api Key 填你在控制台创建的那串。Model ID 按控制台可用列表选一个支持工具调用的模型。填完保存Cline 就能正常对话了。接下来配置 MCP 服务。Cline 的 MCP 配置一般是一个 JSON 文件路径在插件设置里能看到通常是 cline_mcp_settings.json。写入下面这段{ mcpServers: { mcp-test: { command: python, args: [ /你的项目完整路径/mcp-demo-share/main.py ], disabled: false, autoApprove: [ add ] } } }几个字段解释一下command 是启动命令这里用 pythonargs 是参数数组第一个元素是 main.py 的绝对路径Windows 下路径要写成双反斜杠或者正斜杠disabled 为 false 表示启用autoApprove 里填工具名 add表示这个工具调用时不需要每次手动确认调试阶段方便生产环境建议关掉。如果你用的是 Cursor进入 Settings → Cursor Settings → MCP点 Add new MCP serverName 随便填Command 填 pythonArgs 填你的 main.py 绝对路径。Cursor 也支持 JSON 配置字段和上面基本一致。保存配置后客户端会尝试拉起这个进程。状态指示灯变绿说明连接成功。如果一直是红的或者转圈先看客户端的 MCP 日志再对照第五节排查。连接成功后在对话框里输入add 6, 88正常情况下助手会识别出你在调用 add 工具参数 a6、b88然后返回结果 94。你会看到界面上显示「调用了 MCP tool: add」之类的提示这就是一次完整的工具调用闭环。这里有个关键点模型能不能正确调用工具取决于它是否支持 function calling / tool use。如果你选的模型不支持助手可能只是把「add 6, 88」当成普通文本回复不会触发工具。遇到这种情况换一个支持工具调用的模型再试。验证通过后你可以试着改一下 add 函数比如加一个 multiply 工具重启服务看客户端能不能自动发现新工具。这个「改代码 → 重启 → 重新发现」的循环就是后续开发 MCP 服务的日常节奏。5. 本篇常见错误排查401、local proxy failed 与 reading choices新手在这一步翻车的概率最高我把几个高频报错和对应原因列出来你对着日志看基本能定位。第一个是 401 Unauthorized。这个报错通常出现在 AI 编程助手调用模型时不是 MCP 服务本身的问题。原因一般是 API Key 填错、Key 过期、或者 Base URL 写成了带路径的地址。检查方法确认 Base URL 是 https://taotoken.net/api 不要多加 /v1 之类的后缀确认 Key 是从控制台复制完整的一串没有多余空格如果刚重建过 Key旧 Key 会立即失效要换成新的。第二个是 local proxy failed 或 connection refused。这个多半是 MCP 服务进程没起来。可能原因main.py 路径写错客户端拉不到文件Python 解释器路径不对虚拟环境没激活导致依赖缺失或者端口/stdio 被占用。排查顺序是先手动在终端跑一遍 python main.py确认能启动再把配置里的 command 从 python 换成虚拟环境里的绝对路径比如 /你的项目/myenv/bin/pythonWindows 下是 myenv\Scripts\python.exe。这样能确保客户端用的是装了 mcp 的那个解释器。第三个是 reading choices 相关报错比如 Error reading choices 或者返回结构解析失败。这类问题通常出在模型返回格式和客户端预期不一致常见于模型不支持工具调用、或者返回了非标准 JSON。解决办法换一个明确支持 tool use 的模型检查客户端版本是否过旧如果日志里能看到原始返回内容看看是不是被截断了。第四个是 OAuth 相关报错比如 OAuth token invalid 或 authentication failed。如果你用的是 Claude Code 这类走 OAuth 流程的客户端可能是登录态过期。重新走一遍授权流程或者改用 API Key 方式接入。Claude Code 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有环境变量和 settings 的写法。第五个是工具列表为空。服务连上了但助手看不到 add 工具。检查 mcp.tool() 装饰器有没有写对函数有没有被正确注册确认客户端配置里的 autoApprove 工具名和代码里的函数名一致重启客户端有些客户端不会热加载 MCP 配置。第六个是 ModuleNotFoundError: No module named mcp。这是典型的虚拟环境没激活或者客户端用了系统 Python 而不是虚拟环境的 Python。回到第二个报错的解法把 command 指向虚拟环境解释器。排查的核心思路就一条先分清是「模型调用层」的问题还是「MCP 进程层」的问题。401、OAuth 属于前者local proxy failed、ModuleNotFound 属于后者。分层之后定位会快很多。6. 常用 MCP 网站与后续接入入口跑通第一个服务后你大概率会想找现成的 MCP 服务来用或者看看别人怎么写的。下面这几个站点是我平时查资料会去的整理给你。Smithery.ai 是目前体验比较好的 MCP 导航平台每个服务都配了使用说明和示例代码地址是 https://smithery.ai/ 。MCP.so 收录量很大超过两千个服务适合按关键词搜地址是 https://mcp.so/ 。Composio MCP 的特色是每个服务能生成 SSE URL方便直接集成到自己的应用里地址是 https://mcp.composio.dev/ 。Pulse MCP 设计清爽收录了一千五百多个服务还提供了不少用例场景地址是 https://www.pulsemcp.com/ 。这些站点上的服务质量参差不齐用之前建议先看更新时间和 issue 情况涉及文件读写、数据库操作的服务尤其要谨慎别直接连生产环境。如果你想把 MCP 服务用得更深入比如接入 Claude Code 做长期编码任务或者用 Coding Plan 跑 Agent 工作流可以看 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。需要管理多个 Key、查看用量去控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。新建 Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。各客户端的接入细节都在文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到配置问题优先翻这里。最后说个我自己的习惯每写一个新 MCP 工具先在终端单独跑通再用客户端连。终端能跑通说明代码没问题客户端连不上就是配置问题这样排查范围直接砍一半。另外工具函数的 docstring 一定要写清楚模型是靠它来判断什么时候该调用这个工具的写得含糊调用准确率就低。
