构建并接入你的第一个 MCP 服务器

高级

让我们通过构建一个极小的 MCP 服务器并连接它，把一个自定义工具暴露给 Claude。我们会把它保持得尽量精简，让接线方式一目了然 —— 之后你再换上自己真正的逻辑。

我们要构建什么

一个带有单个工具 word_count 的 stdio 服务器，Claude 可以调用它。同样的模式可以扩展到"查询我的数据库"、"开一个工单"等等。

第 1 步 — 服务器

server.py（Python；TypeScript 版本见 MCP 脚手架）：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("text-tools")

@mcp.tool()
def word_count(text: str) -> int:
    """Count the words in a piece of text."""
    return len(text.split())

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

第 2 步 — 声明它

把它添加到仓库根目录的 .mcp.json 中：

{ "mcpServers": {
  "text-tools": { "command": "python", "args": ["server.py"] }
} }

第 3 步 — 连接并测试

在仓库中启动 Claude Code。问它："用 text-tools 服务器统计这段文字的词数：'the quick brown fox'。" Claude 应该会调用 word_count 并报告 4。如果它看不到这个工具，请检查服务器能否独立干净地启动，以及 .mcp.json 的路径是否正确。

第 4 步 — 让它真正可用

把 word_count 替换成你实际的能力 —— 一次数据库查询、一次内部 API 调用、一次文件操作。加入输入校验，并把错误作为结果返回。

安全检查清单

:::warning 服务器 = 代码 + 访问权限

最小权限 —— 只给它所需的数据/操作（保护 Agent）。
校验模型发来的输入。
它返回的不可信数据可能携带提示词注入。
在连接任何第三方服务器之前，先审查它。 :::

我们要构建什么​

第 1 步 — 服务器​

第 2 步 — 声明它​

第 3 步 — 连接并测试​

第 4 步 — 让它真正可用​

安全检查清单​

下一步​