1. 为什么要在 Cline 里手写一个 MCP ToolMCP 全称 Model Context Protocol简单说就是给 AI 助手装上一套「标准插座」模型本身只会聊天但通过 MCP 协议它可以调用你本地写好的函数比如读目录、算数学、查数据库。Cline 是 VSCode 里的一个 AI 编码插件它内置了 MCP 客户端只要你在配置文件里注册一个 MCP ServerCline 就能在对话中自动调用你写的工具。这篇要解决的问题很具体很多人第一次写 MCP Tool卡在三个地方。第一不知道 Server 端代码怎么写才能被识别成 tool第二用系统全局 Python 装依赖装完把环境搞乱或者 Cline 启动时找不到正确的解释器第三Cline 的 MCP 配置 JSON 写错一个字段工具就静默不出现也不报错很难排查。适合谁看已经会用 VSCode 和 Cline、想把自己的一些本地脚本变成 AI 可调用工具的人或者团队里想把内部小工具接进 AI 工作流但不想上云、只想本地跑的人。我试过用 conda 单独开一个环境来跑 MCP Server好处是依赖隔离干净Cline 配置里直接指向那个环境的 python 绝对路径换机器也好迁移。整条链路是conda 建环境 → 装 mcp 依赖 → 写 Server 脚本 → 在 Cline 的 MCP 配置里注册 → 发一条消息验证工具被调用。下面按这个顺序走每一步都给可复制的命令和配置。2. 前置准备conda 环境与 TaoToken 接入配置先说环境。MCP 的 Python SDK 目前主流是mcp包它自带FastMCP这个高层封装写起来比裸协议舒服很多。我建议单独建一个环境名字随意这里叫mcp_demoPython 版本用 3.11兼容性比较稳。conda create -n mcp_demo python3.11 -y conda activate mcp_demo pip install mcp[cli] -i https://pypi.tuna.tsinghua.edu.cn/simple装完可以验证一下python -c from mcp.server.fastmcp import FastMCP; print(ok)输出ok就说明依赖到位。这里有个坑如果你在 base 环境装了 mcp但 Cline 配置里指向的是mcp_demo的 python那启动时会报ModuleNotFoundError: No module named mcp。所以务必确认「装依赖的环境」和「配置里写的 python 路径」是同一个。接下来是模型侧。Cline 本身要调用大模型来驱动对话和工具决策如果你用的是 TaoToken 这类兼容 OpenAI 接口的服务需要在 Cline 的模型设置里填 Base URL 和 API Key。TaoToken 的 API 地址是https://taotoken.net/apiKey 在控制台的 API Keys 页面生成。这一步和 MCP 是两条独立的线模型负责「决定调哪个工具」MCP Server 负责「真正执行工具」两者都要配好链路才通。如果你还没生成 Key可以先去控制台建一个注意 Key 只在创建时显示一次复制保存好。模型 ID 按你实际用的填比如gpt-4o或claude-3-5-sonnet这类具体以你账号下可用的为准。提示MCP Server 跑在本地不消耗模型额度只有 Cline 发起对话、模型决定调用工具时才走 API。所以调试工具逻辑时可以先用mcp dev本地测不必每次都走模型。3. 可复制配置MCP Server 脚本骨架与 Cline settings 片段先写 Server。新建文件base_mcp_tool_study2.py放在你习惯的目录比如/langchain_learn/mcp学习/。核心是用FastMCP初始化然后用mcp_server.tool()装饰器把普通函数注册成工具。装饰器会读取函数的 docstring 作为工具描述所以 docstring 要写清楚参数含义模型靠这个决定怎么传参。import os from typing import Optional from mcp.server.fastmcp import FastMCP mcp_server FastMCP(nameDemoServer, version1.0.0) mcp_server.tool() def list_files(directory: str /work/langchain_learn) - list: 获取指定目录的文件列表 Args: directory (str): 要查询的目录路径支持 ~ 符号 Returns: list: 文件名列表 try: expanded_path os.path.expanduser(directory) return os.listdir(expanded_path) except Exception as e: return [fError: {str(e)}] mcp_server.tool() def calculate(expression: str) - Optional[float]: 执行数学计算支持加减乘除 Args: expression (str): 数学表达式如 3 5 * 2 Returns: float: 计算结果保留两位小数 try: result eval(expression) return round(float(result), 2) except Exception: return None if __name__ __main__: mcp_server.run(transportstdio)注意transportstdio这是 Cline 本地拉起 Server 时用的通信方式Cline 启动这个进程通过标准输入输出收发 JSON-RPC 消息。所以 Server 不需要监听端口也不需要网络。然后是 Cline 侧配置。在 VSCode 里点开 Cline 面板找到 MCP Servers 入口点「已安装」→「配置 MCP 服务器」会打开一个 JSON 文件。把下面这段放进mcpServers对象里{ mcpServers: { myserver2: { command: /miniforge3/envs/mcp_demo/bin/python, args: [ /langchain_learn/mcp学习/base_mcp_tool_study2.py ], disabled: false, autoApprove: [ calculate ], description: 演示服务器含文件查询和计算 } } }三个关键字段必须对齐command是 conda 环境里 python 的绝对路径用conda activate mcp_demo which python查出来args是 Server 脚本的绝对路径autoApprove里写你信任、不需要每次确认的工具名这里放calculatelist_files涉及文件系统读取建议保留人工确认。注意command不要写python这种相对命令Cline 启动子进程时不一定继承你 shell 的 PATH写绝对路径最稳。Windows 下路径用双反斜杠或正斜杠。4. 验证请求一次真实的工具调用与成功结果配置保存后Cline 会自动尝试拉起 Server。回到 MCP Servers 列表myserver2旁边应该出现绿色状态点展开能看到list_files和calculate两个工具。如果没出现先看第 5 节的排查。验证分两步。第一步不经过模型直接确认 Server 能跑/miniforge3/envs/mcp_demo/bin/python /langchain_learn/mcp学习/base_mcp_tool_study2.py这个命令会挂起等待 stdio 输入说明进程正常启动按 CtrlC 退出即可。如果直接报错退出就是脚本或依赖问题。第二步在 Cline 对话框里发一条会触发工具的消息比如帮我算一下 (128 372) * 3 / 5 等于多少模型会判断需要调用calculate因为它在autoApprove里Cline 会直接执行并把结果回填给模型。你会在对话里看到类似「调用工具 calculate参数 expression(128 372) * 3 / 5」的记录然后模型给出结果300.0。实测下来从发消息到看到结果大概两三秒取决于模型响应速度。再测list_files列出 /langchain_learn/mcp学习 目录下的文件这次因为没在autoApprove里Cline 会弹一个确认框你点允许后才会执行返回文件名列表。这一步能跑通说明整条链路——conda 环境、Server 脚本、Cline 注册、模型决策、工具执行——全部打通。5. 本篇常见错排查401、local proxy failed 与 reading choices调试 MCP 时遇到的报错分两类一类是模型侧Cline 调 API一类是工具侧Cline 拉 Server。分开看能省很多时间。401 Unauthorized这是模型 API Key 的问题和 MCP 无关。检查 Cline 模型设置里的 API Key 是否填对、有没有多余空格Base URL 是否是https://taotoken.net/api。如果 Key 刚生成确认复制完整。401 出现时对话根本发不出去工具自然也不会被调用。local proxy failed / connection refusedCline 尝试连接模型服务失败。先确认网络能访问 Base URL再确认 Base URL 没写错路径。有些服务要求结尾带/v1有些不带按你所用服务的文档来。这个错和 MCP Server 状态无关别去改 MCP 配置。Error reading choices / 返回体解析失败通常是模型返回了非预期格式或者 Base URL 指向了一个不兼容 OpenAI 协议的端点。检查你填的模型 ID 是否在该服务下可用。如果换了模型 ID 就好了说明是模型名写错。工具侧报错如果 Cline 里myserver2状态是红的点开看日志。最常见的是ModuleNotFoundError说明command指向的 python 没装 mcp回到第 2 节确认环境。其次是FileNotFoundError说明args里的脚本路径不对用绝对路径再核对一遍。还有一种是 Server 启动了但工具不显示多半是mcp_server.tool()装饰器没加或者函数有语法错误导致模块导入失败。工具被调用但返回 Error看你在函数里 catch 的异常信息。比如list_files返回[Error: [Errno 2] No such file or directory]就是传入的目录不存在。这类错误是业务逻辑问题改函数或改传参即可。提示改完 Server 脚本后要在 Cline 的 MCP 列表里点一下重启该 Server否则跑的还是旧进程。改 Cline 的 JSON 配置后保存Cline 一般会自动重载。6. 把自研工具接进日常编码流工具跑通之后真正有价值的是把它用起来。比如你有一个内部的项目脚手架生成脚本、一个查数据库表结构的脚本、一个跑单元测试的封装都可以按同样的模式包成 MCP Tool。Cline 在写代码时就能直接调用不用你手动切终端。几个实践建议。第一工具函数的 docstring 要写清楚模型靠它决定调用时机和参数描述模糊会导致模型不调用或传错参。第二涉及写操作、删除、执行命令的工具不要放进autoApprove保留人工确认。第三conda 环境按工具用途拆分比如「文件类工具」一个环境、「数据库类工具」一个环境避免依赖冲突。第四Server 脚本里的异常要 catch 并返回可读信息别让异常直接崩掉进程否则 Cline 那边只看到连接断开很难定位。如果你想让 Cline 长期稳定地驱动这些工具做编码和 Agent 任务模型侧的额度消耗会比较持续可以考虑用 Coding Plan 这类面向长期编码场景的方案比按次调用更划算。工具本身跑在本地不产生额外费用成本主要在模型调用上。最后留一个我踩过的坑一开始我把 Server 脚本放在带中文和空格的路径下args里没加引号Cline 启动时路径被截断报cant open file。后来把路径用双引号包起来就好了。所以路径里有空格或中文时JSON 字符串里正常写Cline 会当整体处理但如果你在命令行手动测记得加引号。