1. 为什么要在本地把 MCP 和 Ollama 接起来如果你最近在折腾 AI 工具调用大概率听过 MCPModel Context Protocol这个词。简单说它是一套让大模型和外部工具、数据源对话的规范模型不再只会聊天而是能按约定去调用你写好的函数拿到真实结果再组织回答。Ollama 则是把开源模型跑在你自己开发机上的运行时一条命令就能拉起 gemma、qwen、llama 这类模型数据不出本机。把这两者接起来能做什么你可以让本地模型去查数据库、读文件、调内部接口而不用把请求发到外部服务适合想在开发机上跑通端到端工具调用、又希望模型侧可控的开发者。我这次的目标很明确本地 Ollama 提供模型推理MCP 提供工具中间用 TaoToken 的统一 Key 和 API 通道做接入与联调最后用 curl 验证整条链路是通的。踩过的坑主要集中在两处一是 MCP 服务端和客户端之间的 stdio 会话容易因为初始化超时直接卡死二是本地模型返回的结构化 JSON 偶尔不合法导致工具参数解析失败。下面按可复制的顺序把 config.toml、settings.json 骨架和验证命令都给出来你照着改 IP 和模型名就能跑。2. TaoToken 前置统一 Key 与 API 通道准备TaoToken 在这里扮演的是统一入口你不需要为每个模型或工具单独维护一套鉴权而是拿一个 Key通过它的 API 通道去访问模型对话、编码计划等能力。对本地联调来说好处是模型侧和工具侧的调用凭证收敛到一处排查问题时只需要盯一个通道。先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录然后在控制台里创建 API 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 。创建完把 Key 复制出来后面写进配置文件。API 的基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为 base_url 使用。如果你要验证模型本身是否可用可以先用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条消息确认通道正常如果你打算长期跑编码或 Agent 类任务可以看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。注意Key 只放在本地配置文件或环境变量里不要提交到 Git 仓库。联调阶段建议单独建一个测试用 Key方便随时吊销。3. 可复制配置config.toml 与 settings.json 骨架这一节是整篇的核心。MCP 客户端读取的配置通常分两块一块描述 MCP 服务端怎么启动command、args、env另一块描述模型通道base_url、api_key、model。我用 config.toml 放 MCP 服务端定义用 settings.json 放模型通道和工具开关两者职责分开改起来不容易互相污染。先看 config.toml。这里定义了一个名为 local-tools 的 MCP 服务端用 uv 启动 server.py并把 TaoToken 的 Key 通过环境变量注入避免硬编码# config.toml [mcp] # MCP 服务端列表 [[mcp.servers]] name local-tools command uv args [run, python, server.py] cwd /Users/you/project/mcp-ollama enabled true # 通过环境变量注入统一 Keyserver.py 里用 os.environ 读取 [mcp.servers.env] TAOTOKEN_API_KEY sk-你的TaoTokenKey TAOTOKEN_BASE_URL https://taotoken.net/api # 模型通道配置 [model] provider taotoken base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model gemma3:latest timeout_seconds 60再看 settings.json。它负责工具开关、本地 Ollama 地址和结构化输出约束。Ollama 默认监听 11434如果你在局域网另一台机器上跑把 host 换成对应 IP{ ollama: { host: http://127.0.0.1:11434, model: gemma3:latest, keep_alive: 5m }, mcp: { config_path: ./config.toml, tool_timeout_seconds: 30, auto_approve: false }, taotoken: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY }, logging: { level: info, file: ./logs/mcp-ollama.log } }两个文件的关系是settings.json 指向 config.tomlconfig.toml 里的 env 段把 Key 传给 MCP 服务端进程。这样模型侧和工具侧共用同一个 Key 来源联调时只要确认环境变量注入成功鉴权问题基本就排除了。提示如果你的项目用 uv 管理依赖先执行uv add fastmcp ollama mcp pydantic把 MCP 服务端、Ollama 客户端和结构化输出所需的库一次装齐。4. 验证请求curl 打通模型通道与工具调用配置写完后不要急着跑完整客户端先用 curl 验证 TaoToken 通道是否可达。这一步能快速区分「Key 问题」和「代码问题」。请求模型对话接口curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: gemma3:latest, messages: [ {role: user, content: 只回复两个字通了} ] }如果返回里能看到 choices 字段和正常内容说明 Key 和通道没问题。接着验证本地 Ollama 是否在跑curl http://127.0.0.1:11434/api/tags这条命令会列出本地已拉取的模型。如果列表里没有 gemma3先执行ollama pull gemma3。两个 curl 都通过后再启动 MCP 服务端做工具侧验证uv run python server.py服务端启动后用 MCP Inspector 调试工具列表fastmcp dev server.py浏览器打开 http://127.0.0.1:6274/#tools 能看到 magicoutput 这个工具说明服务端注册成功。最后跑客户端把模型输出和工具调用串起来uv run python client.py预期输出分三段先是 Ollama 返回的结构化 JSON包含 response 和 tool 字段然后是工具执行结果形如输入参数obj1:Wombatobj2:Dog,魔法输出Hello MCPMCP Hello最后是持久MCP会话已关闭。三段都出现端到端就算跑通了。5. 本篇常见错排查联调阶段最容易卡在几个固定位置我按出现频率排一下。第一个是 MCP 会话初始化超时报MCP会话未能及时初始化。原因通常是 server.py 启动慢或 stdio 管道没接上。排查方法单独运行uv run python server.py确认它不报错再检查 config.toml 里的 cwd 是不是项目绝对路径相对路径在不同工作目录下会失效。第二个是 Ollama 返回的 JSON 不合法报model_validate_json解析失败。本地小模型在结构化输出上不如大模型稳定解决办法是在 system 提示里明确要求「只输出 JSON不要额外解释」并把 format 参数设成 response_model 的 schema。如果还是偶发失败加一层重试最多三次。第三个是工具参数类型不匹配。MCP 服务端声明的 inputSchema 里 obj1、obj2 是 string但模型有时会返回数字。在 convert_json_type_to_python_type 里已经做了映射如果遇到未覆盖的类型补一个分支返回(str, ...)兜底即可。第四个是 Key 注入失败报 401。检查 config.toml 的 env 段变量名和代码里os.environ.get(TAOTOKEN_API_KEY)是否一致注意大小写。另外确认 Key 没有多余空格复制时容易带上换行。第五个是端口占用Ollama 的 11434 或 Inspector 的 6274 被别的进程占了。用lsof -i :11434查一下必要时改 settings.json 里的 host 端口。注意排障时优先看 logs/mcp-ollama.log里面会记录 MCP 会话的启动和工具调用时间戳比在终端里翻输出快得多。6. 接入与长期使用的分流建议跑通之后接下来怎么用取决于你的场景。如果你只是偶尔验证模型通道是否正常直接用模型对话页面最省事https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。如果你要把这套 MCPOllama 接进日常编码流程或者跑长期 Agent 任务建议走 Coding Plan配额和通道更稳定https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入细节和参数说明以官方文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_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 。API 基础地址统一用 https://taotoken.net/api 不要带查询参数。最后给一个实用习惯把 config.toml 和 settings.json 里的 Key 换成环境变量引用本地用.env加载提交仓库时把.env加进.gitignore。这样换机器或换 Key 时只改一处联调链路不会因为凭证散落而反复出问题。