Mcp on Kalend's Blog

自己写一个 MCP Server：从协议到实战的完整指南

Mon, 08 Jun 2026 08:30:00 +0800

MCP Hub 上现成的 Server 有几百个，但真正落到自己手上——公司内部 API、私有数据源、定制化工具链——没有一个现成的能直接用。这篇文章带你用 Python FastMCP 3.x 从零写一个文件管理 MCP Server，跑通本地调试、远程部署的完整链路。

MCP 协议核心概念速览

三个角色

角色	职责	例子
Host	发起连接的 LLM 应用	Claude Desktop、Cursor、VS Code Copilot
Client	Host 内部与 Server 通信的组件	Claude 内置的 MCP Client
Server	提供工具、数据、提示词的服务	你写的那个

关系很简单：Host 包含 Client，Client 连接 Server。

三个核心能力

Tools：让 LLM 调用函数（计算、查数据库、操作文件）
Resources：让 LLM 读取数据（配置文件、数据库内容）
Prompts：预定义的提示词模板，复用对话模式

两种传输方式

方式	场景	协议
stdio	本地运行，Host 直接启动你的进程	JSON-RPC over stdin/stdout
Streamable HTTP	远程部署，Host 通过 HTTP 连接	HTTP POST + SSE

MCP ≠ Function Calling

这是最大的概念误区。Function Calling 是单个模型厂商的私有接口（比如 OpenAI 的 tool_use），而 MCP 是一个开放协议——任何 LLM、任何工具，只要遵循协议规范就能互通。你可以把它理解为「工具调用界的 USB 接口」。

实战：搭建文件管理 MCP Server

环境准备

1
2
3
4
5
6
7
8
9


# Python >= 3.10
python3 --version

# 创建虚拟环境
python3 -m venv mcp-env
source mcp-env/bin/activate

# 安装 FastMCP（当前最新 3.4.x，别装旧版）
pip install fastmcp

注意：网上大量教程还在用 FastMCP 2.x 的 API（@mcp.server.tool()、FastMCP.from_tools() 等），这些在 3.x 已经全部改了。如果你照抄旧代码，会直接报错。

完整代码

创建 file_server.py：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104


import os
import json
from pathlib import Path
from fastmcp import FastMCP

mcp = FastMCP(name="FileManager")

@mcp.tool
def list_files(dir_path: str) -> str:
 """列出指定目录下的文件和子目录。
 
 Args:
 dir_path: 要列出的目录路径
 """
 path = Path(dir_path).resolve()
 if not path.exists():
 return json.dumps({"error": f"路径不存在: {dir_path}"}, ensure_ascii=False)
 if not path.is_dir():
 return json.dumps({"error": f"不是目录: {dir_path}"}, ensure_ascii=False)
 
 entries = []
 for item in sorted(path.iterdir()):
 entry = {
 "name": item.name,
 "type": "dir" if item.is_dir() else "file",
 "size": item.stat().st_size if item.is_file() else None,
 }
 entries.append(entry)
 
 return json.dumps({
 "path": str(path),
 "count": len(entries),
 "entries": entries,
 }, ensure_ascii=False, indent=2)


@mcp.tool
def read_file(file_path: str) -> str:
 """读取文件内容（文本文件，限制 10MB）。
 
 Args:
 file_path: 文件路径
 """
 path = Path(file_path).resolve()
 if not path.exists():
 return json.dumps({"error": f"文件不存在: {file_path}"}, ensure_ascii=False)
 if not path.is_file():
 return json.dumps({"error": f"不是文件: {file_path}"}, ensure_ascii=False)
 if path.stat().st_size > 10 * 1024 * 1024:
 return json.dumps({"error": "文件超过 10MB 限制"}, ensure_ascii=False)
 
 try:
 content = path.read_text(encoding="utf-8")
 return json.dumps({
 "path": str(path),
 "size": path.stat().st_size,
 "content": content,
 }, ensure_ascii=False)
 except UnicodeDecodeError:
 return json.dumps({"error": "不是文本文件或编码不支持"}, ensure_ascii=False)


@mcp.tool
def search_files(pattern: str, directory: str = ".") -> str:
 """在指定目录下按文件名模式搜索文件。
 
 Args:
 pattern: 搜索模式，支持通配符（如 *.py、test_*）
 directory: 搜索的根目录，默认为当前目录
 """
 path = Path(directory).resolve()
 if not path.exists():
 return json.dumps({"error": f"目录不存在: {directory}"}, ensure_ascii=False)
 
 matches = list(path.glob(f"**/{pattern}"))
 results = [
 {
 "path": str(m.relative_to(path)),
 "type": "dir" if m.is_dir() else "file",
 "size": m.stat().st_size if m.is_file() else None,
 }
 for m in sorted(matches)[:100] # 限制最多 100 条
 ]
 
 return json.dumps({
 "pattern": pattern,
 "directory": str(path),
 "count": len(results),
 "results": results,
 }, ensure_ascii=False, indent=2)


@mcp.resource("resource://cwd")
def get_cwd() -> str:
 """返回当前工作目录信息。"""
 return json.dumps({
 "cwd": os.getcwd(),
 "user": os.environ.get("USER", "unknown"),
 "home": str(Path.home()),
 }, ensure_ascii=False, indent=2)


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

代码要点

@mcp.tool 装饰器把普通函数变成 MCP Tool，函数名就是工具名，docstring 自动变成工具描述
参数用 Python type hints（str、int），FastMCP 自动生成 JSON Schema
@mcp.resource("resource://cwd") 暴露一个只读数据源，Client 可以按 URI 请求
所有返回值统一用 JSON 字符串，LLM 解析起来更可靠
路径用 Path.resolve() 处理，避免相对路径歧义

测试运行

1
2
3
4
5


# 启动 Server（stdio 模式，等待 JSON-RPC 输入）
python file_server.py

# 用 MCP Inspector 调试（需要 Node.js）
npx @modelcontextprotocol/inspector python file_server.py

MCP Inspector 会打开一个 Web 界面，你可以可视化地调用每个 Tool、查看 Schema、检查返回值。

集成到 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或对应路径：

1
2
3
4
5
6
7
8
9


{
 "mcpServers": {
 "file-manager": {
 "command": "python",
 "args": ["/绝对路径/file_server.py"],
 "cwd": "/你的工作目录"
 }
 }
}

重启 Claude Desktop，你的文件管理工具就出现在工具列表里了。

从本地到远程：部署你的 MCP Server

stdio → Streamable HTTP

本地开发用 stdio（简单直接），生产环境需要暴露 HTTP 接口。FastMCP 3.x 内置支持：

1
2
3


# 只改最后一行
if __name__ == "__main__":
 mcp.run(transport="streamable-http", host="0.0.0.0", port=8080)

或者用命令行直接启动：

1

fastmcp run file_server.py --transport streamable-http --port 8080

认证

远程部署必须加认证。MCP 规范推荐 OAuth 2.1（2025 年 6 月 spec 确定）。不要用裸 API Key——明文传输不安全。

FastMCP 3.x 支持通过中间件集成 OAuth：

1
2
3
4


from fastmcp import FastMCP

mcp = FastMCP(name="FileManager", auth_config=...)
# 具体配置参见 FastMCP 官方文档的 Authentication 章节

Docker 容器化

1
2
3
4
5
6
7
8
9


FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY file_server.py .

EXPOSE 8080
CMD ["fastmcp", "run", "file_server.py", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8080"]

1
2


docker build -t file-mcp-server .
docker run -p 8080:8080 file-mcp-server

踩坑实录：我开发 MCP Server 时遇到的 5 个坑

坑 1：FastMCP 版本陷阱

FastMCP 从 1.x → 2.x → 3.x 快速迭代，网上 90% 的教程用的都是过时 API。典型的坑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# ❌ FastMCP 2.x 写法（3.x 报错）
from fastmcp import FastMCP, Context

@mcp.tool()
async def my_tool(ctx: Context) -> str:
 ...

# ✅ FastMCP 3.x 写法
@mcp.tool
def my_tool() -> str:
 ...

教训：写代码前先 pip show fastmcp 确认版本，再去查对应版本文档。

坑 2：把 MCP 当 Function Calling 写

MCP 不只是「换个方式调用函数」。Function Calling 是单次请求-响应，MCP 是持久化的能力暴露——你的 Server 一直活着，Client 随时可以调用任何 Tool、读取任何 Resource。设计思路应该是「我这个 Server 能提供什么能力」，而不是「我这个函数怎么被调用」。

坑 3：Schema 不精确，LLM 瞎调

参数的 type hints 和 docstring 直接决定 LLM 理解你工具的准确度。下面是反面教材：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# ❌ LLM 不知道 limit 是什么范围、offset 从 0 还是 1 开始
def query(page, size):
 """查询数据"""
 ...

# ✅ 类型、范围、含义都写清楚
def query_users(
 page: int = 1, 
 size: int = 20,
) -> str:
 """分页查询用户列表。

 Args:
 page: 页码，从 1 开始
 size: 每页条数，最大 100
 """
 ...

坑 4：调试困难

MCP 用 JSON-RPC over stdio，不像 REST API 可以直接 curl 测试。你没法手动构造 JSON-RPC 消息发到 stdin。

解决方案：用 MCP Inspector（npx @modelcontextprotocol/inspector），它提供完整的可视化调试界面。或者用 FastMCP Client 写测试脚本：

1
2
3
4
5
6
7
8
9


from fastmcp import Client

async def test():
 async with Client("file_server.py") as client:
 result = await client.call_tool("list_files", {"dir_path": "/tmp"})
 print(result)

import asyncio
asyncio.run(test())

坑 5：Node 版本不兼容

如果你用 TypeScript SDK 开发 MCP Server，需要 Node >= 18。低版本会出现诡异的 ERR_MODULE_NOT_FOUND 或 SyntaxError。如果你用 npx @modelcontextprotocol/inspector 调试 Python Server，也需要确保 Node 版本够新。

1
2
3
4
5
6


# 检查版本
node --version # 需要 >= 18

# 推荐用 nvm 管理
nvm install 20
nvm use 20

总结：什么时候自己写 vs 用现成的

场景	建议
标准 API（GitHub、Slack、数据库）	用现成 Server（MCP Hub 上找）
内部工具、私有 API、定制逻辑	自己写
需要特定认证流程	自己写
简单的文件/数据操作	自己写（几十行代码搞定）

MCP Server 开发本身不难——FastMCP 一个装饰器搞定工具定义，type hints 自动生成 Schema。难的是理解协议设计理念（能力暴露 vs 函数调用）和避开版本陷阱。

推荐资源：

MCP 官方文档 — 协议规范和概念
FastMCP 官方文档 — 最新 API 参考
MCP Hub — 现成 Server 搜索

下一篇我会聊 MCP + Cursor 的进阶玩法——怎么让你的 MCP Server 真正融入日常开发工作流。

MCP 协议入门：让 AI 工具连接一切的万能接口

Sun, 07 Jun 2026 08:30:00 +0800

MCP 协议入门：让 AI 工具连接一切的万能接口

你用 Claude 查数据库、用 Cursor 调 API、用 VS Code 写代码——每个 AI 工具连外部能力的方式都不一样，开发者疲于适配。MCP 结束了这一切。

先说结论

MCP（Model Context Protocol）就是 AI 世界的"万能转接头"。

什么意思？以前你给 Claude 写个插件，只有 Claude 能用。给 Cursor 写个扩展，只有 Cursor 能用。现在你写一个 MCP Server，所有支持 MCP 的工具——Claude Desktop、ChatGPT、Cursor、VS Code Copilot、Windsurf——都能直接调用。

写一次，到处能用。这就是 MCP 的核心价值。

MCP 到底是什么

一句话定义：AI 应用连接外部系统的开放协议。

类比你就懂了。USB-C 统一了充电口——以前出门带五根线，现在一根搞定。MCP 做的是同样的事：统一 AI 调用外部工具的接口。

以前 Claude 想读文件，得用 Claude 自己的插件格式。Cursor 想查数据库，得用 Cursor 自己的扩展 API。每个 AI 工具都搞一套，开发者写一次适配要重复 N 遍。MCP 把这些全部标准化了。

谁做的？Anthropic（Claude 背后的公司），2024 年 11 月开源推出。不是闭源产品，是真正的开放协议——规范仓库 8300+ Star，官方 Server 参考实现仓库 86000+ Star，社区贡献活跃。

这里有个容易搞混的点：MCP 不是 Function Calling 的替代品。Function Calling 是"模型能调用函数"这个能力，MCP 是在它之上的一层标准化协议——定义了工具怎么描述、怎么发现、怎么调用。类比：Function Calling 是发动机，MCP 是传动轴。不是替代关系，是上下层关系。

协议的治理也很规范。MCP 有完整的 SEP（Specification Enhancement Proposal）流程，类似 Python 的 PEP。社区通过 SEP 提案来讨论和推进协议演进，目前已有 30+ 个 SEP。这意味着 MCP 不是一家公司说了算，而是有社区共识机制的开放标准。

为什么 2026 年必须懂 MCP

数据说话，不讲故事。

npm 包月下载量 1.55 亿次。 这是 TypeScript SDK 的数据，Python SDK 也已经迭代到 1.27.2 版本。一个协议相关的 SDK 能有这个量级，说明生态已经非常成熟。

协议本身也在快速演进：

时间	版本	关键更新
2025-03	2025-03-26	首个正式版本发布
2025-06	2025-06-18	tool annotations、structured output、elicitation
2025-09	Registry 上线	可搜索可发现的 Server 市场
2025-11	2025-11-25	最新稳定版
2026-05	2026-07-28-RC	下一个大版本候选，含 Tasks、MCP Apps

支持 MCP 的工具列表已经覆盖所有主流平台：Claude Desktop、ChatGPT、VS Code Copilot、Cursor、Windsurf、Zed、Replit、Continue、通义灵码……

注意 ChatGPT 和 VS Code 也在列表里。MCP 不是 Claude 专属，它正在成为全行业的事实标准。Anthropic 把它开源出来，OpenAI 接了，微软接了——这就不是一家公司的生态了，而是整个 AI 行业的基础设施。

一句话总结：2026 年不懂 MCP 的开发者，就像 2015 年不懂 REST API 的后端开发者。不是学不学的问题，是早晚要学的问题。

MCP 怎么工作：三层核心概念

别被架构图吓到，核心就三个角色，记住它们就行。

Host（宿主）：你用的 AI 应用。Claude Desktop、Cursor、VS Code，这些就是 Host。它负责管理所有 MCP 连接，决定什么时候调用什么工具。

Client（客户端）：Host 内部自动创建的通信组件。每连接一个 Server，Host 就自动创建一个对应的 Client。你作为用户不需要手动配置这个——它是透明的。

Server（服务端）：提供具体能力的独立程序。连接数据库、读写文件、搜索网页、调用第三方 API——都是 Server 的事。Server 可以跑在本地（stdio 传输），也可以跑在远程（Streamable HTTP 传输）。

一个简化示意：

1
2
3
4


Claude Desktop (Host)
 ├── Client 1 ←→ Filesystem Server（读写本地文件）
 ├── Client 2 ←→ Database Server（查数据库）
 └── Client 3 ←→ Web Search Server（搜索网页）

Host 想读文件？问 Client 1。想查数据库？问 Client 2。整个过程对用户来说就是正常聊天——AI 自己决定调哪个工具。

通信协议用的是 JSON-RPC 2.0，非常轻量。本地场景用 stdio（标准输入输出），远程场景用 Streamable HTTP。如果你熟悉 LSP（Language Server Protocol），会觉得这个架构很眼熟——确实，MCP 的设计灵感就来自 LSP。

Server 暴露三种能力，官方叫 Primitives（原语）：

Tools：可调用的函数。这是最常用的。 比如执行 SQL 查询、创建文件、发送邮件。可以理解为"动作"。每次 AI 说"我来帮你执行 XXX"，背后大概率就是调了一个 Tool。

Resources：可读取的数据或文件。比如数据库表结构、配置文件内容、API 文档。可以理解为"信息"。和 Tool 的区别是 Resource 是只读的，AI 只是"看"一眼，不会改变什么。

Prompts：预定义的提示模板。比如"用 XX 风格写代码"的标准提示词，或者"按 XX 格式输出报告"的模板。可以理解为"指令模板"。

实际开发中 90% 的场景只用 Tools。Resources 和 Prompts 是锦上添花，不用急着学。

亲测演示：5 分钟跑通你的第一个 MCP

不用写代码。现成的 Server 拿来就能用。这是 MCP 的设计哲学：先用起来，再理解原理。

以 Claude Desktop + 官方文件系统 Server 为例。

Step 1：安装 Claude Desktop

去 claude.ai/download 下载安装。macOS 和 Windows 都支持。

Step 2：确保有 Node.js

终端执行 node --version，能看到版本号就行。没有就去 nodejs.org 装 LTS 版。很多官方 Server 都是基于 Node.js 的。

Step 3：编辑配置文件

打开 Claude Desktop → 点击顶部菜单 Claude → Settings → Developer → Edit Config。

这会打开一个 JSON 配置文件，写入以下内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


{
 "mcpServers": {
 "filesystem": {
 "command": "npx",
 "args": [
 "-y",
 "@modelcontextprotocol/server-filesystem",
 "/Users/你的用户名/Desktop",
 "/Users/你的用户名/Downloads"
 ]
 }
 }
}

把路径换成你自己的实际路径。Windows 用户把 /Users/ 改成 C:\\Users\\。

这个配置告诉 Claude Desktop：启动时自动运行 filesystem 这个 Server，并授权它访问指定的目录。

Step 4：重启 Claude Desktop，开始对话

重启后在聊天框里试试这些：

“帮我看看桌面上有哪些文件”——Claude 会弹出权限请求，你确认后它就能读取文件列表了。

“把 Downloads 里最大的 5 个文件列出来”——它会扫描目录并排序。

“帮我创建一个 notes.txt，写上今天的待办事项”——它真的能创建文件。

全程不用写一行代码。现成的 Server 拿来就跑。

如果你用的是 Cursor，流程更简单：Settings → MCP → Add New Server → 粘贴配置 → 重启。VS Code Copilot 也类似，在 settings.json 里配置 mcp 字段即可。

想试试更多 Server？去官方 GitHub 仓库 modelcontextprotocol/servers，里面有几十个开箱即用的 Server——数据库、Git、Brave Search、Slack、Google Drive……复制配置就能用。

MCP vs Function Calling vs Agent：别再搞混了

这三个概念经常被混在一起说，其实完全不在一个层级。

概念	是什么	解决什么问题	类比
Function Calling	模型调用函数的能力	让 LLM 能触发动作	电灯开关
MCP	标准化的工具发现和调用协议	让所有工具对所有平台可用	家里的电路系统
Agent	利用工具链自主完成复杂任务的应用	替人干活	你本人

打个比方：Function Calling 是开关——让 AI “能"调用工具。MCP 是电路系统——规定所有电器用统一的接口。Agent 是你——决定开哪个灯、用哪个电器。

它们是三层关系，不是三选一。不存在"用 MCP 就不用 Function Calling"这种说法——Agent 内部用 Function Calling 来调工具，而这些工具通过 MCP 来暴露和发现。

写在最后

MCP 生态正在爆发式增长。官方 Registry 已上线，像 npm 一样可以搜索和安装 Server。社区贡献的 Server 数量每周都在增加，主流开发工具全面接入。

如果你还在为每个 AI 工具单独写适配代码——停下来，试试 MCP。

下一篇我会教你从零写一个自己的 MCP Server。从"用工具"到"造工具”。

关注 varkm，持续获取 AI 实战内容。