1. 为什么要在本地用 Stdio 跑一个 MCP ServerMCP Server 说白了就是给大模型装的一双手模型本身只会聊天但通过 MCP 协议它能调用你写好的函数去查数据库、调接口、读文件。而 Stdio 模式是 MCP 里最省事的一种传输方式——客户端把 Server 当成一个子进程启动双方通过标准输入输出收发 JSON-RPC 消息不需要开端口、不需要配网络、不需要考虑鉴权暴露问题。这套方案适合谁适合手上有内部系统比如工作汇报、订单、日志平台想快速接给 AI 用的人适合本地开发调试阶段不想折腾 HTTP 服务的人也适合把 MCP Server 打包进桌面客户端Claude Desktop、Cline、ChatBox 这类当插件用的人。你只要本机有 Python 3.11装一个 fastmcp几十行代码就能把「查公司列表」「查某人某月提交了几次汇报」这种能力暴露给模型。但这里有个容易被忽略的点MCP Server 负责的是「工具注册与调用」它本身不产生智能。真正理解用户那句「张三上个月交了几次汇报」并决定调用哪个工具、传什么参数的是背后的模型。所以一个完整的链路是客户端 → 模型负责决策→ MCP Server负责执行→ 你的数据库/接口。模型这一环如果直连各家厂商Key 管理、通道切换、额度分散会非常烦。我这次的做法是让模型请求统一走 TaoToken 的 API 通道一个 Key 覆盖多种模型MCP Server 专注做工具执行两边职责分清调试起来也干净。下面从零开始先建 Server再配模型通道最后跑一次完整的本地验证确认工具注册和请求链路都正常。2. 环境准备与 fastmcp 安装踩坑记录先把地基打好。Python 版本这块别偷懒官方要求 3.11 及以上我实测 3.10 在部分依赖上会报类型相关的错尤其是 fastmcp 依赖的 pydantic 新版本对 typing 特性有要求。用python --version确认一下低于 3.11 就先升级。创建独立虚拟环境避免污染全局包python -m venv mcp-env # Windows mcp-env\Scripts\activate # macOS / Linux source mcp-env/bin/activate装依赖。fastmcp 是核心pymysql 用于直连数据库requests 用于调内部 HTTP 接口pip install fastmcp pymysql requests这里有个坑我踩过fastmcp 迭代很快不同小版本 API 有差异。如果你照着老教程写from mcp.server.fastmcp import FastMCP在新版里可能导入失败。当前推荐直接用顶层包from fastmcp import FastMCP装完验证一下版本心里有数pip show fastmcp输出里能看到 Version 字段。如果后面遇到AttributeError: FastMCP object has no attribute tool这类怪问题八成是版本对不上先pip install -U fastmcp升到最新再试。目录结构建议这样别把所有东西堆一个文件里后面加工具会乱mcp-demo/ ├── server.py # MCP Server 主文件 ├── config.py # 数据库/接口配置 └── requirements.txt把配置抽出来单独放是因为数据库密码、接口地址这类东西不该硬编码在业务逻辑里。config.py长这样# config.py DB_CONFIG { host: 127.0.0.1, port: 3306, user: root, password: your_password, database: work_state, charset: utf8mb4, } INTERNAL_API_BASE http://localhost:8087注意 host 我写的是127.0.0.1而不是10.0.6.1这种内网地址本地调试就用本地库别一上来连生产出问题不好排查。数据库表结构假设有一张ws_log_record汇报记录和sys_user用户字段包含submission_date、work_item、create_by、nick_name这是后面 SQL 的基础。环境这块还有个小提醒Windows 下如果pymysql连库报编码错误检查charset是不是utf8mb4以及数据库本身建库时用的字符集。我遇到过表里存了 emoji 导致查询报错的情况统一 utf8mb4 就没事了。3. 用 fastmcp 写一个可复制的 Stdio MCP Server现在写核心文件server.py。整个 Server 的结构分四块初始化实例、注册工具Tools、注册资源Resources、启动。先看完整代码再逐段拆。# server.py from fastmcp import FastMCP import pymysql import requests from config import DB_CONFIG, INTERNAL_API_BASE mcp FastMCP(nameWork Report Server) mcp.tool(description获取公司列表) def get_company_list() - list[dict]: 调用内部接口获取全部公司返回公司ID与名称列表。 try: url f{INTERNAL_API_BASE}/record/logrecord/getAllCompany resp requests.get(url, timeout5) resp.raise_for_status() data resp.json() if isinstance(data, list): return data return [data] except Exception as e: return [{error: str(e)}] mcp.tool(description获取指定用户在某年月的汇报内容及提交次数) def get_user_submissions(nick_name: str, year: int, month: int) - dict: 按昵称、年份、月份查询汇报记录。 try: conn pymysql.connect(**DB_CONFIG) cursor conn.cursor(pymysql.cursors.DictCursor) sql SELECT lr.submission_date, lr.work_item FROM ws_log_record lr JOIN sys_user u ON lr.create_by u.user_name WHERE u.nick_name %s AND YEAR(lr.submission_date) %s AND MONTH(lr.submission_date) %s ORDER BY lr.submission_date cursor.execute(sql, (nick_name, year, month)) records cursor.fetchall() cursor.close() conn.close() return {count: len(records), records: records} except Exception as e: return {error: str(e)} mcp.tool(description获取指定公司在某年月的部门月度统计) def get_dept_month_statistics(company_id: int, year: int, month: int) - dict: 调用内部接口获取部门统计queryFirstDept 固定为 false。 try: url f{INTERNAL_API_BASE}/back/api/logRecord/getDeptMonthStatisticsByCompanyId params { companyId: company_id, year: year, month: month, queryFirstDept: false, } resp requests.get(url, paramsparams, timeout5) resp.raise_for_status() return resp.json() except Exception as e: return {error: str(e)} mcp.resource(resource://config) def get_config() - dict: 提供应用配置信息。 return {version: 1.0, author: MyTeam} mcp.resource(greetings://{name}) def personalized_greeting(name: str) - str: 生成个性化问候语。 return fHello, {name}! Welcome to the MCP server. if __name__ __main__: mcp.run()逐段说。FastMCP(nameWork Report Server)创建实例这个名字会出现在客户端工具列表里起个能看懂的名字。mcp.tool(description...)是重点description 不是写给人看的注释是写给模型看的——模型靠它判断「用户这个问题该不该调这个工具」。所以描述要写清楚「这个工具干什么、参数是什么含义」别写「查询数据」这种模糊话。get_company_list的返回类型我标了list[dict]但内部接口如果返回的是单个对象而不是数组直接 return 会让 MCP 的输出校验失败报is not of type array。所以我在里面加了一层判断不是 list 就包成 list。这个细节后面排障会再讲。get_user_submissions是直连数据库的典型写法用参数化查询防注入DictCursor让结果直接是字典列表方便序列化。注意连接用完要close()Stdio 模式下 Server 是长驻进程连接泄漏会拖垮数据库。get_dept_month_statistics演示了带固定参数的接口调用queryFirstDept写死false这种业务约定直接固化在代码里别让模型去猜。Resources 部分resource://config是静态资源greetings://{name}是动态资源路径参数用{}占位。资源是「只读信息」工具是「执行动作」两者定位不同别混用。启动就一行mcp.run()默认走 Stdio。如果你要改成 HTTP 模式才需要传 host/port本地 Stdio 不用管。4. 接入 TaoToken 统一 Key 打通模型调用链路Server 写完了但它现在只是个「工具仓库」得有个模型来驱动它。这一步把模型请求接到 TaoToken 的 API 通道上一个 Key 搞定多模型调用省得每个厂商单独配。先拿 Key。访问 https://taotoken.net/api-keys 登录后在控制台创建 API Key复制出来形如sk-xxxx的字符串。这个 Key 就是后面所有模型请求的凭证别硬编码进代码用环境变量。配置 Base URL 和 Key。TaoToken 的 API 入口是https://taotoken.net/api兼容 OpenAI 的接口格式所以任何支持自定义 Base URL 的客户端都能接。以环境变量方式配置# macOS / Linux export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api # Windows PowerShell $env:TAOTOKEN_API_KEYsk-你的key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类工具配置写在 settings 里。以settings.json为例路径和字段名要对齐{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }注意这里三件套必须齐全Base URL、Key、Model ID。少任何一个都会在请求时报鉴权失败或模型不存在。Model ID 要写 TaoToken 支持的模型名别自己编。如果你用 Cline 或类似的 VS Code 插件配置项在插件设置里同样是三件套{ apiProvider: openai, openAiBaseUrl: https://taotoken.net/api, openAiApiKey: sk-你的key, openAiModelId: gpt-4o }Codex 用户如果走auth.json结构类似把 base_url 和 api_key 填进去即可。核心就一句话Base URL 指向 TaoTokenKey 用 TaoToken 的Model ID 填你要用的模型。配好之后模型请求会统一经过 TaoToken 通道MCP Server 那边完全不用改——它只负责执行工具不关心模型从哪来。这种解耦的好处是哪天你想换模型只改客户端配置Server 代码一行不动。想先验证 Key 通不通可以直接用 curl 打一发curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: ping}] }返回里有choices字段就说明通道正常。这一步过了再往下接 MCP。5. 本地验证工具注册与请求链路完整跑通现在把 Server 和模型接起来跑一次端到端验证。我用 ChatBox 做客户端演示其他支持 MCP 的客户端流程类似。第一步在 ChatBox 里添加 MCP Server。配置方式选 Stdio命令填 Python 解释器路径加脚本路径{ mcpServers: { work-report: { command: python, args: [/absolute/path/to/mcp-demo/server.py], env: { PYTHONUNBUFFERED: 1 } } } }command用虚拟环境里的 python 绝对路径最稳别依赖全局 PATH。args里脚本路径也写绝对路径相对路径在客户端启动子进程时容易找不到文件。PYTHONUNBUFFERED1是为了让日志实时输出方便看启动过程。第二步启动后看客户端日志。正常情况下能看到 Server 启动、工具注册的信息类似Registered tool: get_company_list Registered tool: get_user_submissions Registered tool: get_dept_month_statistics Registered resource: resource://config Registered resource: greetings://{name}看到这几行说明工具注册成功。如果这里就报错多半是导入失败或语法问题回到终端手动python server.py跑一遍看报什么。第三步发一条自然语言请求测试链路。在对话框输入帮我查一下张三在 2025 年 10 月提交了几次工作汇报模型收到后会先判断该调get_user_submissions然后生成调用参数。你在日志里能看到类似这样的请求体{ model: gpt-4o, messages: [ {role: system, content: 你是一个管理助手}, {role: user, content: 帮我查一下张三在 2025 年 10 月提交了几次工作汇报} ], tools: [ { type: function, function: { name: get_user_submissions, description: 获取指定用户在某年月的汇报内容及提交次数, parameters: { type: object, properties: { nick_name: {type: string}, year: {type: integer}, month: {type: integer} }, required: [nick_name, year, month] } } } ] }模型返回的tool_calls里会带上参数{ tool_calls: [ { id: call_abc123, type: function, function: { name: get_user_submissions, arguments: {\nick_name\: \张三\, \year\: 2025, \month\: 10} } } ] }Server 执行 SQL返回结果{ count: 22, records: [ {submission_date: 2025-10-01, work_item: ...}, {submission_date: 2025-10-02, work_item: ...} ] }模型拿到结果后用自然语言回复「张三在 2025 年 10 月共提交了 22 次工作汇报。」到这一步整条链路就通了用户提问 → 模型决策 → MCP 工具执行 → 结果回传 → 模型组织语言。验证成功的标志有三个日志里工具已加载、请求体里 tools 字段包含你的工具、返回结果里 count 和 records 有真实数据。三个都满足说明 Server 和模型通道都正常。6. 常见报错排查401、输出校验、OAuth 与代理问题跑通之后把几个高频报错整理一下遇到不用慌。401 鉴权失败。典型报错是工具返回{msg: 请求访问/record/logrecord/getAllCompany认证失败无法访问系统资源, code: 401}。这通常不是 MCP 的问题而是你 Server 里调的那个内部接口需要 token而你没带。解决办法是在requests.get里加上内部系统的认证头比如headers{Authorization: Bearer xxx}。注意区分这是内部接口的 401和 TaoToken 的 401 是两码事。TaoToken 的 401 一般出现在模型请求阶段报invalid api key检查环境变量里的 Key 有没有复制全、有没有多余空格。Output validation error: ... is not of type array。这个报错的意思是工具声明的返回类型和实际返回不匹配。比如你标了- list[dict]但接口返回的是单个对象{...}MCP 校验就挂了。解决办法就是前面get_company_list里那层判断不是 list 就包一层。或者干脆把返回类型改成dict别硬标 list。local proxy failed / 连接超时。这类报错通常是网络层问题。先确认INTERNAL_API_BASE指向的地址本机能不能通用curl或浏览器访问一下。如果是数据库连接超时检查DB_CONFIG里的 host、port 是否正确防火墙有没有放行。Stdio 模式下 Server 是本地进程不涉及跨机网络所以问题基本都在你调用的下游服务上。OAuth 相关报错。有些客户端在接 MCP 时会尝试走 OAuth 流程报OAuth flow failed或unauthorized_client。本地 Stdio 模式一般不需要 OAuth如果客户端强制要走检查它的 MCP 配置里有没有把认证方式设成 none 或 stdio。别在 Stdio 场景下配 OAuth那是 HTTP 远程模式才需要的。工具没被调用。模型回复了但没调工具或者调了不存在的工具。先看工具的 description 写得够不够清楚模型判断不了就不会调。其次确认客户端确实加载了 Server日志里有没有注册信息。还有一种情况是模型能力不够换个更强的模型试试。中文乱码。数据库返回的中文变成问号或乱码检查charset是不是utf8mb4以及连接时有没有指定。Windows 终端下打印中文乱码是终端编码问题不影响实际数据可以在代码里加# -*- coding: utf-8 -*-或设置PYTHONIOENCODINGutf-8。排查思路统一是先看报错在哪一层模型请求层 / MCP 协议层 / 下游服务层再针对性查。模型层看 Key 和 Base URL协议层看工具注册和返回类型下游层看接口和数据库连通性。7. 把 MCP Server 用起来的几个实用建议工具描述是给模型看的不是给人看的。我见过太多人把 description 写成「查询数据」结果模型根本不知道该在什么场景调它。正确写法是「获取指定用户在某一年的某一月提交的工作汇报条数和明细参数为员工昵称、年份、月份」。把使用场景、参数含义都写进去模型判断准确率会高很多。返回结构尽量稳定。工具返回的 JSON 字段名别今天叫count明天叫total模型是靠字段名理解数据的。固定一套 schema长期用下来省心。Stdio 模式下 Server 是长驻进程注意资源释放。数据库连接、文件句柄用完就关别指望进程退出时自动回收。我习惯用try/finally或者上下文管理器包住连接。调试阶段把日志打开。PYTHONUNBUFFERED1加上在关键位置print一下入参和返回比盲猜快得多。等稳定了再去掉。模型通道这块统一走 TaoToken 的好处是 Key 只有一个换模型不用改 Server。想试不同模型对工具调用的支持度改客户端配置里的 Model ID 就行。需要看模型列表和额度去控制台 https://taotoken.net/console 看想直接对话测试模型能力用 https://taotoken.net/model-chat 快速验证长期跑编码或 Agent 任务Coding Plan 更划算入口在 https://taotoken.net/coding-plan 。接入细节和参数说明在文档 https://taotoken.net/doc 里都有遇到配置问题先翻文档比搜帖子快。最后一句实在话MCP Server 的价值不在于代码多复杂而在于它把你已有的系统能力「翻译」成了模型能调用的形式。先把一个工具跑通再慢慢加别一上来就想接十个接口。