MCP Server 搭建教程，5 步让 AI 接入本地工具

MCP 是 Model Context Protocol 的缩写，2024 年底由 Anthropic 提出的开放协议。它的核心目的是让大模型通过标准接口接入任意外部工具，包括数据库、文件系统、API、办公软件、浏览器等。本文是 2026 年最新版搭建教程，5 步教你从零搭建一个 MCP server，让 Claude 接入本地工具。

整个流程包括理解协议、选择技术栈、编写 server、配置 Claude Desktop 或 Claude Code、测试调用。每步都给出具体的代码和命令。读完文章你能拥有一个真正可用的自定义 MCP server，可以让 AI 调你电脑上的任何东西。

为什么要自己搭 MCP server

虽然官方和社区已经提供了不少现成的 MCP server，但自己搭一个有 4 个理由。第一是接入私有工具。公司内部的 API 或者数据库不会有现成的 server，必须自己写。第二是定制行为。社区版可能功能太多或者太少，自定义版本能精确控制。

第三是性能优化。社区 server 是通用方案，给特定场景调优后性能能提升好几倍。第四是学习理解。亲手实现一遍 MCP server，能彻底理解整个协议是怎么工作的，对调试和故障排查特别有帮助。

我自己第一个 MCP server 是为了让 Claude 接入公司内部的 Jira。社区版 Jira MCP 性能差且接口不全，重写一个只花了 1 天，每天给团队省下大量手工查 ticket 的时间。

第一步：理解 MCP 协议核心概念

MCP 协议有三大核心概念。第一是 Tools，AI 可以调用的函数，比如 get_user_info、send_email。第二是 Resources，AI 可以读取的数据源，比如配置文件、数据库表。第三是 Prompts，预设的指令模板，比如 weekly_report、code_review。

通信走 JSON-RPC 2.0 标准，可以选 stdio 或者 HTTP/SSE 两种传输方式。stdio 适合本地工具，AI 客户端通过子进程启动 server，标准输入输出通信。HTTP/SSE 适合远程工具，server 部署在云端，客户端走 HTTP 连接。

新手建议从 stdio 开始。开发环境简单，不用考虑端口、CORS、鉴权这些问题。本地工具搞定后再考虑要不要做 HTTP 版本上云。

第二步：选择语言和 SDK

Anthropic 官方提供了 Python、TypeScript、Rust 三种 SDK。Python 是社区使用最广的，文档最全，适合大多数场景。TypeScript 适合前端背景的开发者或者需要和 Node 生态集成的场景。Rust 适合性能敏感的服务。

Python SDK 装一行命令：pip install mcp。TypeScript SDK 是 @modelcontextprotocol/sdk，npm install 即可。两者 API 设计高度一致，切换语言基本不用重学。

我推荐 Python。社区生态最活跃，遇到问题搜得到答案。如果你的工具已经是某个语言写的，也可以选对应 SDK，避免跨语言调用。本文后续示例都用 Python 演示。

第三步：编写一个最简单的 MCP server

新建一个 weather_mcp.py 文件，写下基础骨架。先导入 mcp 包，初始化 Server 对象，然后用装饰器注册一个 tool。tool 函数接收参数，调用外部 API 拿数据，返回字符串结果。

具体代码逻辑大约 30 行。包括 server 元数据声明（名称、版本）、tool 函数实现（city 参数，调用 OpenWeather API）、main 入口（启动 stdio transport）。完整代码可以在 Anthropic 官方 GitHub 仓库 modelcontextprotocol 找到示例。

写完后用 python weather_mcp.py 运行，正常情况下不会有任何输出，说明 server 正在等待 JSON-RPC 消息。这就对了，stdio transport 没有交互界面，所有通信通过标准输入输出。

第四步：在 Claude Desktop 或 Claude Code 配置 server

Claude Desktop 用户编辑配置文件。Mac 路径是 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 路径是 %APPDATA%\Claude\claude_desktop_config.json。文件里加上 mcpServers 段，指定 server 的命令和参数。

具体结构是 {"mcpServers": {"weather": {"command": "python", "args": ["/Users/yourname/weather_mcp.py"]}}}。重启 Claude Desktop 后，新 server 会被自动加载。如果加载失败查看 Claude 日志能看到错误原因。

Claude Code 用户用 claude mcp add 命令注册，或者编辑 ~/.config/claude/mcp.json。语法略有不同但概念一致。Claude Code 还支持项目级 MCP 配置，写在 .mcp.json 放在项目根目录，只对当前项目生效。

第五步：测试和调试

在 Claude 里输入 帮我查下北京今天的天气，Claude 会自动识别可用工具，调用 weather MCP server 的 get_weather 函数，参数 city=北京，拿到天气数据返回给你。这就完成了一次完整的 MCP 调用。

调试遇到问题主要看两处。一是 Claude 客户端的日志，记录所有 MCP 调用和返回。二是 MCP server 自己的日志，stderr 输出会被 Claude 捕获显示。两边日志对照看一般能定位问题。

常见错误包括 server 启动失败（Python 路径不对）、tool 不被识别（装饰器没生效）、返回格式错误（必须是字符串或者特定 dict 结构）。新手最容易踩的是返回值类型，记得用 str 包一下保险。

进阶：加上 Resources 和 Prompts

Tools 是 MCP 最基础的功能。要让 server 更强还需要加 Resources 和 Prompts。Resources 是数据源，比如把 logs 目录注册为一个 Resource，Claude 可以列出文件、读取内容。区别于 Tools 是 Resources 更像静态数据。

Prompts 是预设指令模板。比如建一个 code_review prompt，参数是文件路径，模板内容是 请审查这个文件的代码质量，关注 5 个维度。用户在 Claude 输入 /code_review path=/foo/bar.py 就会触发整个评审流程。

Resources 和 Prompts 都用类似装饰器注册。一个完整的生产级 MCP server 通常包括 5 到 10 个 tools、3 到 5 个 resources、5 到 8 个 prompts。形成一个完整的工具包。

常见 MCP server 案例与思路

第一个是 GitHub MCP。让 Claude 能操作 GitHub 仓库，包括读 issue、写 comment、提交 PR、跑 actions。社区有现成版本，叫 @modelcontextprotocol/server-github，直接安装即可。

第二个是数据库 MCP。让 Claude 能查询公司数据库，安全做法是只暴露 SELECT 权限，禁止 UPDATE 和 DELETE。常见实现是包装 SQLAlchemy 或者 psycopg，限定 schema 范围。

第三个是 Slack MCP。让 Claude 能在 Slack 频道发消息、读取历史。需要 Slack App OAuth token，注意权限范围最小化。我的团队用这个让 Claude 每周自动发周报到指定频道。

第四个是邮件 MCP。接入 Gmail 或者 Outlook IMAP，让 Claude 能读邮件、写回复。注意邮件涉及隐私，要慎重处理鉴权。建议只读模式上线。

第五个是浏览器 MCP。让 Claude 控制 Playwright 或者 Puppeteer，自动浏览网页、截图、填表。强大但风险大，建议在沙盒环境运行。

安全和性能注意事项

安全是 MCP server 第一要务。Claude 调你的 server 等于把电脑控制权部分交给 AI。第一条规则是最小权限，server 只暴露必要的功能。第二条是审计日志，记录所有调用方便事后排查。第三条是沙盒隔离，敏感操作在 docker 或者虚拟机内执行。

性能上，stdio transport 启动开销约 100 毫秒，每次调用走 JSON-RPC 序列化反序列化也有 10 到 50 毫秒延迟。对单次调用没事，对批量调用要考虑批处理优化。一次 list_files 比 100 次 read_file 快得多。

资源占用方面，一个简单 MCP server 内存约 30 到 50 MB。复杂的（比如包含浏览器自动化）可能到几百 MB。如果同时运行多个 server，电脑内存压力会上来，按需启用。

生态发展和未来方向

MCP 在 2025 年迎来爆发。GitHub、Cloudflare、Linear、Notion、Cursor 等主流工具都推出了官方 MCP server。一个统计是到 2026 年 5 月，公开的 MCP server 已经超过 1500 个，覆盖 90% 常见软件。

下一阶段的重点是远程 MCP。让 server 部署在云端，用户不需要本地安装，通过 OAuth 直接连接。这种模式更适合企业部署，权限管理也更集中。Anthropic 在 2026 年初已经发布 HTTP/SSE 远程 MCP 的标准，正在普及中。

长期看，MCP 有可能成为大模型工具调用的事实标准。OpenAI、Google 等其他厂商虽然各有自己的协议，但越来越多的开发者倾向 MCP 这种开放方案。未来可能不止 Claude 用 MCP，其他 AI 也会兼容。

常见问题 FAQ

MCP 和 Function Calling 有什么区别

Function Calling 是 OpenAI 早期推的方式，让 AI 在对话中输出 JSON 让用户解析执行。MCP 更进一步，定义了完整的协议栈，包括传输层、消息格式、工具发现、状态管理。MCP 是 Function Calling 的工程化升级版。

我的 MCP server 会被 Claude 用作训练数据吗

不会。MCP 通信内容不被 Anthropic 用于训练。这点和 Claude API 的政策一致。但要注意，你 server 的代码如果开源在 GitHub，Anthropic 抓公开网页训练时可能会包含，这是另一个层面的问题。

没有编程背景能用 MCP 吗

能。MCP 客户端使用门槛低，安装现成 server 不需要写代码。装一个 filesystem MCP 立即让 Claude 能读写本地文件。门槛主要在写 MCP server，那才需要编程。

MCP server 收费吗

协议本身免费开源。社区 MCP server 大多免费。某些商业产品（比如某些 SaaS 的官方 MCP）可能需要订阅。自己搭的 server 自然不收费，但要算电费和服务器钱。

MCP 安全吗，会不会被恶意 server 攻击

理论上有风险。一个恶意 MCP server 可以执行任意代码。安全实践是只安装可信来源的 server，不要随便从陌生人那里拿配置文件粘贴。社区有审计工具帮你检查 MCP server 的代码。

MCP 是 2025 年开发者圈最值得学的新协议之一。掌握它意味着能让 AI 接入任何你想要的工具，可能性几乎无限。希望本教程让你迈出第一步，搭出自己的第一个 MCP server，玩出更多新花样。