Claude Code怎么接入本地MCP？配置、调用验证与移除教程

Claude Code 接入本地 MCP 的核心是登记一个启动命令：Claude Code 启动 Python 子进程，通过标准输入输出发现工具，再决定是否调用。下面使用只做整数加法的服务器，把环境、配置、结果验证和移除走完整遍；不需要数据库，也不用给示例配置 API 密钥。

先确认版本和实际要连接的对象

本教程需要 Python 3.10 及以上，测试采用 Windows PowerShell、Python 3.11 和官方 mcp==2.2.0。截至 2026 年 10 月 1 日，官方 Python SDK v2 使用 MCPServer；网上 v1 的 FastMCP 示例不要直接混入本环境。连接对象是你写的本地服务器，并非把 Claude 模型下载到电脑。

你需要已经安装、能够正常使用的 Claude Code。先执行 claude --version 和 claude mcp add --help；若第一条报找不到命令，先解决安装或 PATH。这里实际核对了 Claude Code 2.1.160 的 CLI 帮助，并验证了 Python 服务器的协议调用；未使用登录账号完成 Claude 模型对话，下面的对话步骤是基于官方说明的操作流程。

第一步：建立一个无外部依赖的本地工具

下面假定使用新目录 C:\mcp-demo。如果目录已有内容，直接进入自己的测试目录，避免覆盖原项目。

mkdir C:\mcp-demo
cd C:\mcp-demo
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install "mcp==2.2.0"

新建 server.py，保存以下完整内容：

from mcp.server import MCPServer

mcp = MCPServer("LocalCalc")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two integers and return their exact sum."""
    return a + b

if __name__ == "__main__":
    mcp.run(transport="stdio")

函数名 add 是工具名，文档字符串是工具说明，a: int 与 b: int 提供输入类型。mcp.run(transport="stdio") 让程序通过标准输入输出收发协议消息。不要再用 print() 往服务器 stdout 打启动横幅；调试日志应写 stderr，否则客户端可能把日志当成协议消息。

第二步：用绝对路径登记到当前项目

在同一个 PowerShell 窗口执行：

$py = (Resolve-Path .\.venv\Scripts\python.exe).Path
$server = (Resolve-Path .\server.py).Path
claude mcp add --transport stdio --scope local local-calc -- $py $server
claude mcp get local-calc
claude mcp list

这里的 local-calc 是配置名称，LocalCalc 是服务器自报名称，add 是工具名，三者不用相同。双横线 -- 后面的内容原样传给子进程；绝对路径可以避免 Claude Code 从另一工作目录启动时找不到虚拟环境。

--scope local 表示只对当前项目中的你可用。需要团队共享时才考虑 project；该模式写入项目的 .mcp.json，其他人使用时还涉及信任批准。不要为了共享，把个人密码写进仓库。user 则用于你跨项目复用的配置。

第三步：分别验证连接与真实调用

1. 在这个项目目录启动 claude，输入 /mcp 检查 local-calc 的状态及可用工具。连接正常只能说明协议接通。
2. 提交：“请调用 local-calc 的 add 工具，参数 a=2、b=3，并把工具返回值原样列出。”如出现工具授权提示，确认工具与参数后再允许。
3. 核对实际调用记录里是否出现 add 和两个整数参数，以及返回值是否为 5。仅有模型回答“2+3=5”不能证明工具被调用。

本地独立 SDK 客户端已验证该服务器：输入 {"a":2,"b":3} 时，结构化结果为 {"result":5}；将 a 改为无法转换为整数的字符串时，返回工具错误。这个测试证明服务器与参数处理有效，不能代替你的 Claude 登录、订阅或权限验证。

连接失败时按证据排查

不再使用时移除配置

claude mcp remove --scope local local-calc
claude mcp list

在登记配置的同一个项目执行移除，检查列表中不再出现这个名称。移除连接不会删除 server.py 或虚拟环境；以后仍可重新登记。

相关问题与官方资料

为什么没有先开端口？ 本文使用 stdio，Claude Code 启动子进程即可。连接远端 MCP 才需要 HTTP 地址及对应认证，不能把 HTTP 配置中的 URL 当成这里的启动命令。

会自动获得读写电脑全部文件的权限吗？ 这个示例只定义加法函数，没有文件访问代码。实际权限取决于服务器实现和进程运行身份；接入第三方服务器前应查看它提供的工具与访问范围。

参考：Claude Code MCP 配置、作用域与管理命令；官方 Python SDK v2 入门和版本要求；SDK 传输说明与 stdio 的使用边界。