MCP Server setup tutorial, 5 steps to connect AI to local tools

MCP is the abbreviation of Model Context Protocol, an open protocol proposed by Anthropic at the end of 2024. Its core purpose is to allow large models to access any external tools through standard interfaces, including databases, file systems, APIs, office software, browsers, etc. This article is the latest version of the 2026 construction tutorial. It teaches you in 5 steps to build an MCP server from scratch and let Claude access local tools.

The entire process includes understanding the protocol, selecting the technology stack, writing the server, configuring Claude Desktop or Claude Code, and testing the call. Specific codes and commands are given for each step. After reading the article, you will have a truly usable custom MCP server that can let AI adjust anything on your computer.

为什么要自己搭 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 will explode in 2025. Mainstream tools such as GitHub, Cloudflare, Linear, Notion, and Cursor have launched official MCP servers. One statistic is that by May 2026, there will be more than 1,500 public MCP servers, covering 90% of common software.

The next phase focuses on remote MCPs. Let the server be deployed in the cloud, and users do not need to install it locally and connect directly through OAuth. This model is more suitable for enterprise deployment, and permission management is more centralized. Anthropic has released the standard for HTTP/SSE remote MCP in early 2026, which is becoming popular.

In the long term, MCP may become the de facto standard for large model tool invocation. Although other manufacturers such as OpenAI and Google have their own protocols, more and more developers are leaning toward open solutions like MCP. In the future, not only Claude may use MCP, but other AIs may also be compatible.

FAQ

What is the difference between MCP and Function Calling?

Function Calling is an early approach promoted by OpenAI, which allows AI to output JSON in conversations for users to parse and execute. MCP goes one step further and defines a complete protocol stack, including transport layer, message format, tool discovery, and status management. MCP is an engineered upgraded version of Function Calling.

Will my MCP server be used by Claude as training data?

Won't. MCP communication content is not used by Anthropic for training. This is consistent with Claude API policy. But be aware that if your server code is open sourced on GitHub, it may be included when Anthropic captures public web pages for training. This is a problem on another level.

Can I use MCP without a programming background?

able. The threshold for using the MCP client is low, and there is no need to write code to install a ready-made server. Installing a filesystem MCP immediately enables Claude to read and write local files. The threshold is mainly to write MCP server, then programming is required.

Is there any charge for MCP server?

The protocol itself is free and open source. Community MCP servers are mostly free. Some commercial products (such as official MCPs for certain SaaS) may require a subscription. Of course, there is no charge for setting up your own server, but you have to account for the electricity and server costs.

Is MCP safe? Can it be attacked by malicious servers?

There are theoretical risks. A malicious MCP server can execute arbitrary code. The safe practice is to only install servers from trusted sources, and do not just paste configuration files from strangers. The community has audit tools to help you check the MCP server code.

MCP is one of the most worth learning new protocols in the developer circle in 2025. Mastering it means giving AI access to any tool you want, and the possibilities are almost endless. I hope this tutorial will help you take the first step to build your first MCP server and play more new tricks.