1. 为什么要在 Cursor 里跑一个本地 MCP 服务如果你最近在折腾 Cursor大概率会碰到一个词MCP。它的全称是 Model Context Protocol翻译过来叫模型上下文协议。你可以把它理解成给 AI 装的一个「外挂工具箱」——平时大模型只能靠训练时记住的知识回答问题但接上 MCP 之后它就能调用你本地写好的函数、查数据库、读文件、算汇率甚至去请求外部接口。对开发者来说这意味着 Cursor 不再只是一个补全代码的编辑器而是一个能真正「动手干活」的智能体。这篇内容聚焦一件事在 Cursor 里从零搭一个本地 MCP 服务并且跑通一次完整的问答链路。所谓问答链路就是你用自然语言提问Cursor 识别出需要调用哪个工具把参数传给你的本地 Python 服务服务执行完把结果返回最后 Cursor 用自然语言把答案讲给你听。整个过程你会看到工具被调用的日志、参数和返回值。适合谁看写过一点 Python、装过 Cursor、想搞清楚 MCP 到底怎么落地的人。不需要你懂协议细节我会给一份可以直接复制的config.toml骨架和一份server_demo.py再配上启动命令、日志排查和一次真实的验证请求。中间涉及模型调用通道的地方我会用 TaoToken 的统一 Key 和 API 通道来配置这样你不用在多个平台之间来回切换 Key。先说清楚一个容易混淆的点MCP 服务本身不负责「思考」它只负责「执行」。思考是 Cursor 背后的大模型干的执行是你本地这个 Python 进程干的。两者通过标准输入输出或者 HTTP 通信。理解这一点后面排查问题会轻松很多——报错要么出在模型侧没识别出该调工具要么出在服务侧工具执行失败。2. 前置准备TaoToken 统一 Key 与 API 通道在动手写服务之前先把模型调用这条链路理顺。Cursor 本身需要配置一个模型提供方而 MCP 服务里如果也要调模型比如做二次总结同样需要一个稳定的 API 通道。我这边习惯用 TaoToken 来统一管理原因是它把 Key 和 API 地址收敛成一套配置一次到处能用省得每个工具单独填。你需要拿到两样东西一个是 API Key一个是 API 基础地址。地址是https://taotoken.net/api注意这个地址后面不要加多余的路径很多 404 都是因为手抖多拼了一段。Key 的获取入口在控制台的 API Keys 页面登录后新建一个就行建议按项目命名方便后面区分。拿到 Key 之后先别急着往 Cursor 里塞用一条 curl 命令验证通道是否通。这一步很关键因为如果通道本身有问题后面 MCP 联调时你会分不清是服务写错了还是 Key 失效了。curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 只回复两个字通了}] }如果返回的 JSON 里choices[0].message.content是「通了」说明 Key 和通道都没问题。如果返回 401检查 Key 有没有复制全返回 404检查地址是不是写成了https://taotoken.net/api/带斜杠或者多拼了/v1之外的东西。这一步过了再往下走。提示把 Key 写进环境变量而不是硬编码在代码里比如export TAOTOKEN_API_KEYxxx后面 Python 服务里用os.getenv读取。这样即使代码传到 Git 上也不会泄露。关于模型选择问答链路里我一般用响应快的小模型做工具调用判断用能力强一点的模型做最终回答。TaoToken 的模型对话入口可以直接在网页上试不同模型的效果确认哪个模型对你的工具描述理解得准再写进配置。这个试错过程比盲配省时间。3. 可复制的 config.toml 骨架与 server_demo.py现在进入正题。Cursor 的 MCP 配置有两种常见形态一种是 JSON 的mcp.json一种是 TOML 的config.toml。这篇用 TOML 骨架因为结构更清晰注释也好写。先在你的项目根目录建一个.cursor文件夹里面放config.toml。# .cursor/config.toml # Cursor 本地 MCP 服务配置骨架 [mcp_servers.local_demo] # 启动命令用 python 直接跑脚本 command python # 脚本的绝对路径Windows 用正斜杠或双反斜杠 args [E:/mcp-playground/server_demo.py] # 工作目录建议设成脚本所在目录避免相对路径找不到文件 cwd E:/mcp-playground # 环境变量把 TaoToken 的 Key 和地址注入进去 env { TAOTOKEN_API_KEY 你的_API_KEY, TAOTOKEN_BASE_URL https://taotoken.net/api } # 如果服务需要长时间运行可以加超时和自动重启 # startup_timeout_ms 20000 # restart_on_failure true几个参数说明一下。command写python的前提是你的 Python 在系统 PATH 里如果用的是虚拟环境这里要写虚拟环境里 python 的绝对路径比如E:/mcp-playground/.venv/Scripts/python.exe。args里是脚本路径Windows 下路径分隔符容易出问题统一用正斜杠最省事。cwd很多人会漏结果脚本里用相对路径读文件就报错加上它稳妥。env这块就是把上一步的 Key 和地址传进去服务里读环境变量即可。接下来是server_demo.py。这份代码基于 FastMCP提供两个工具一个汇率换算一个四则运算。汇率接口如果请求失败会走备用汇率保证离线也能演示。# server_demo.py import os import requests from typing import Dict, Literal from pydantic import BaseModel from mcp.server.fastmcp import FastMCP # 创建 MCP 服务器实例名字会显示在 Cursor 的工具列表里 mcp FastMCP(local_demo) ConversionDirection Literal[CNY_to_USD, USD_to_CNY] class CurrencyConversionResponse(BaseModel): original_amount: float converted_amount: float original_currency: str target_currency: str exchange_rate: float def get_exchange_rates() - Dict[str, float]: 获取汇率失败时返回备用值 try: resp requests.get( https://api.exchangerate-api.com/v4/latest/USD, timeout5 ) data resp.json() usd_to_cny data[rates][CNY] return { USD_to_CNY: usd_to_cny, CNY_to_USD: 1 / usd_to_cny, } except Exception as e: print(f[warn] 汇率接口失败走备用值: {e}) return {USD_to_CNY: 7.20, CNY_to_USD: 0.139} mcp.tool() def convert_currency(amount: float, direction: ConversionDirection) - CurrencyConversionResponse: 在人民币和美元之间换算金额。 参数 amount 是要换算的金额direction 是方向取值 CNY_to_USD 或 USD_to_CNY。 rates get_exchange_rates() if direction CNY_to_USD: original_currency, target_currency CNY, USD rate rates[CNY_to_USD] else: original_currency, target_currency USD, CNY rate rates[USD_to_CNY] converted round(amount * rate, 2) return CurrencyConversionResponse( original_amountamount, converted_amountconverted, original_currencyoriginal_currency, target_currencytarget_currency, exchange_rateround(rate, 4), ) mcp.tool() def calculate(expression: str) - float: 计算四则运算表达式例如 1 2 * 3。 try: return eval(expression, {__builtins__: {}}, {}) except Exception as e: return f计算错误: {e} if __name__ __main__: mcp.run()注意calculate里我把eval的__builtins__清空了只允许纯数学表达式避免执行任意代码。这是本地服务的安全底线别图省事直接eval(expression)。依赖安装用 pip 就行pip install mcp[cli] requests pydantic装完先单独跑一下服务确认能起来python server_demo.py如果终端没有报错、光标停住不动说明服务在等待连接这是正常的。按 CtrlC 退出再去 Cursor 里配。4. 启动、接入与一次问答请求的验证配置文件和脚本都就位后回到 Cursor。打开设置里的 MCP 面板它会读取你项目下的.cursor/config.toml。如果没自动加载手动点一下刷新。加载成功后local_demo这个服务前面会出现绿色小点展开能看到convert_currency和calculate两个工具。如果小点是灰的或者红的先看 Cursor 的 MCP 日志面板里面会打印服务启动时的 stderr。最常见的两个错误一是command找不到 python二是脚本路径写错。日志里会明确告诉你No such file or directory或者ModuleNotFoundError照着改就行。服务连上后开一个新的对话窗口用自然语言提问。我实测下来下面这句触发工具调用很稳帮我算一下 10000 人民币能换多少美元顺便算一下 (35 17) * 3 等于多少。Cursor 会先识别出需要调用convert_currency参数是amount10000, directionCNY_to_USD然后调用calculate参数是expression(35 17) * 3。你会在对话里看到工具调用的折叠块展开能看到入参和返回值。最终回答大概是「10000 人民币约等于 1390 美元另外 (3517)*3 等于 156」。如果工具没被调用而是模型直接瞎编了一个答案说明工具描述没写清楚或者当前模型对工具调用的支持不好。这时候回到 TaoToken 的模型对话页面换一个工具调用能力强的模型再试。工具描述里的 docstring 很关键convert_currency的 docstring 明确写了参数取值模型才能正确填direction。验证成功的标志有三个Cursor 界面出现工具调用卡片、你的 Python 服务终端打印出请求日志、最终回答里的数字和工具返回值一致。三个都满足链路就通了。5. 本篇常见错误排查联调阶段踩的坑基本集中在下面几类我按出现频率排一下。第一类是服务起不来。报ModuleNotFoundError: No module named mcp说明依赖装到了别的 Python 环境。用which pythonWindows 用where python确认当前命令对应的解释器再用这个解释器去pip install。如果你用了虚拟环境config.toml里的command必须指向虚拟环境里的 python不能写全局的。第二类是路径问题。报cant open file server_demo.py: [Errno 2] No such file or directory就是args里的路径不对。用绝对路径别用./server_demo.py这种相对路径因为 Cursor 启动服务时的工作目录不一定是你的项目根目录。cwd也一并设上。第三类是工具不出现。服务绿点了但工具列表是空的。这通常是mcp.tool()装饰器没生效检查一下函数是不是定义在mcp FastMCP(...)之后以及有没有在if __name__ __main__:里调用mcp.run()。另外函数如果有语法错误服务启动时就会崩日志里能看到 traceback。第四类是模型不调工具。服务正常、工具也在但提问后模型直接回答不调用。先确认你问的问题确实需要工具——问「今天天气」它当然不会调汇率工具。然后检查工具 docstring 是否描述了使用场景。如果还不行换模型。工具调用对模型能力有要求不是所有模型都支持得好。第五类是汇率接口超时。因为走了外部 API网络波动时会卡住。代码里我加了timeout5和备用汇率正常情况下 5 秒内会返回。如果你看到日志里打印[warn] 汇率接口失败说明走了备用值结果依然可用只是汇率不是实时的。注意排查时永远先看服务终端的 stderr再看 Cursor 的 MCP 日志最后才怀疑模型。顺序反了会浪费很多时间。6. 把链路固定下来Key 管理与后续扩展链路跑通之后建议做两件事让这套东西能长期用。第一件是把 Key 从config.toml里挪到系统环境变量config.toml里只写env { TAOTOKEN_API_KEY ${TAOTOKEN_API_KEY} }这种引用形式避免 Key 跟着项目文件到处跑。第二件是给服务加日志在mcp.run()之前配一下 logging把每次工具调用的入参和耗时打到文件里出问题时能回溯。后续想扩展的话加新工具就是在server_demo.py里再写一个带mcp.tool()的函数重启服务Cursor 会自动发现。比如加一个读本地 CSV 的工具、加一个查 SQLite 的工具都是同样的套路。工具多了之后docstring 要写得更精确否则模型会在多个工具之间选错。如果你打算把 MCP 用在更重的编码场景比如让 Cursor 自动跑测试、改配置、提交代码那模型调用量会明显上升这时候用 Coding Plan 这类按量方案会比单次调用划算。接入文档里有完整的参数说明和示例遇到通道层面的问题可以直接对照排查。模型对话入口适合快速验证某个模型对工具描述的理解程度省得每次都改代码试。最后留一个我自己的习惯每加一个新工具先用curl或者 Python 脚本单独调一次工具函数确认逻辑没问题再交给 Cursor 联调。这样出问题时能立刻定位是工具本身的问题还是模型调用的问题比在 Cursor 里反复试快得多。