从 0 开发一个 MCP Server：手把手教你构建 AI 工具调用能力

现有 AI 模型「不够聪明」的根本原因，是缺乏访问外部工具与实时数据的能力。你希望 Claude 查数据库、GPT 调 API、Cursor 操作文件系统——这正是 MCP 要解决的问题。工具调用能力经历了 Function Calling → Plugins → MCP 的演进：Function Calling 绑定单一厂商；Plugins 生态封闭；MCP 则提供跨模型、跨客户端的开放标准。

Anthropic 于 2024 年 11 月设计 MCP，核心目标是标准化 AI 与外部工具的通信协议，解决 N 个模型 × M 个工具 = N×M 定制化集成的困境。读完本文，你将能独立开发并部署一个生产可用的 MCP Server。

• 重复造轮子：为 Cursor、Claude Desktop、VS Code 各写一套文件系统接入逻辑。
• 换模型即重写：从 Claude 迁到 GPT，集成层全部推倒重来。
• 资源与提示词无标准：Function Calling 只管「调函数」，无法原生暴露只读资源与可复用 Prompt 模板。
• 调试黑盒：工具调用失败时缺乏统一 Inspector 与 JSON-RPC 日志。

Client 是 AI 模型侧（Claude Desktop、Cursor、自定义客户端）；Server 是你开发的能力提供方。二者通过 JSON-RPC 2.0 通信，传输方式支持 stdio（本地进程）与 HTTP + SSE（远程服务）。生命周期为：初始化握手 → 能力协商 → 请求/响应 → 关闭。

Server 暴露三大核心能力：

• Tools：AI 可调用的函数（搜索、计算、数据库查询）
• Resources：AI 可读取的资源（文件、URL、数据流）
• Prompts：预定义的提示词模板

Python（推荐新手）：官方 SDK mcp，简洁易上手。TypeScript（推荐前端/全栈）：官方 SDK @modelcontextprotocol/sdk。本文以 Python 为主，TypeScript 做对照说明。

# Python
python -m venv .venv
source .venv/bin/activate
pip install mcp

# TypeScript（对照）
npm init -y
npm install @modelcontextprotocol/sdk

推荐项目结构：

my-mcp-server/
├── server.py
├── tools/
│   ├── calculator.py
│   └── web_search.py
├── resources/
│   └── file_reader.py
├── prompts/
│   └── templates.py
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md

调试工具：MCP Inspector（官方调试 UI）、Claude Desktop 本地联调、Cursor 的 .cursor/mcp.json 配置。官方文档见 modelcontextprotocol.io。

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-first-server")

@mcp.tool()
def say_hello(name: str) -> str:
    """向指定的人打招呼"""
    return f"Hello, {name}! 这是你的第一个 MCP 工具。"

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

python server.py
npx @modelcontextprotocol/inspector python server.py

在 Cursor 的 .cursor/mcp.json 或 Claude Desktop 的 claude_desktop_config.json 中配置 command + args 指向 python server.py，重启后验证工具出现在 AI 上下文中。

工具的基本结构：函数签名即文档——参数类型、返回类型、docstring 会被 MCP 转为 JSON Schema 供模型理解。命名使用 snake_case，错误应返回结构化信息而非裸异常。

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="搜索关键词")
    max_results: int = Field(default=5, description="最多返回结果数")
    language: str = Field(default="zh", description="结果语言")

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """执行网络搜索，返回相关结果列表"""
    ...

五个实用工具建议作为练手清单：

• 计算器：数学表达式求值（eval 需沙箱限制）
• 文件读写：读取/写入允许目录内的本地文件
• HTTP 请求：调用外部 REST API
• 数据库查询：执行只读 SQL
• 时间工具：获取当前时间、时区转换

import httpx

@mcp.tool()
async def fetch_url(url: str) -> str:
    """获取指定 URL 的内容"""
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.text

错误处理最佳实践：返回结构化错误信息、设置超时（建议 30s）、在 Server 层做权限校验，避免将凭证泄露到客户端配置。

Resource 与 Tool 的区别：Resource 是数据提供者（只读），Tool 是动作执行者。通过 URI 寻址：file://、http://、custom://。

@mcp.resource("config://app-settings")
def get_app_settings() -> str:
  return json.dumps({"version": "1.0", "env": "production"})

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    user = db.query_user(user_id)
    return json.dumps(user)

资源类型涵盖文本（text/plain、application/json）、二进制（图片、PDF）与流式资源（实时数据）。文件系统资源服务器可实现：列出目录、读取文件、监听文件变化（资源订阅）。

MCP Prompt 是预定义的提示词片段，支持动态参数注入，提升一致性与可维护性。可定义包含 user 与 assistant 的多轮模板，适用于代码审查、面试模拟、调试助手等场景。

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"请对以下 {language} 代码进行审查..."
            )
        )
    ]

mcp = FastMCP("remote-server", transport="streamable-http")

if __name__ == "__main__":
    mcp.run(host="0.0.0.0", port=8000)

生产环境须配置 Bearer Token 认证、API Key 校验中间件、CORS 与请求频率限制。凭证集中在 Server 层管理，而非分散到各客户端。

可引用数据点 1：截至 2026 年，MCP 生态已有超过 10,000 个 Server。

可引用数据点 2：企业采用 MCP 后，工具集成开发成本降幅约 38–55%（行业调研区间）。

可引用数据点 3：MCP Python SDK 在 PyPI 月下载量已突破 500 万（2026 Q2）。

使用 MCP Inspector 启动调试界面，测试 Tools 调用、查看 JSON-RPC 请求/响应日志、模拟错误场景。单元测试可启动子进程 Server 并通过 ClientSession 调用：

from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

async with stdio_client(StdioServerParameters(
    command="python", args=["server.py"]
)) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("calculate", {"expression": "2 + 2"})
        assert result.content[0].text == "4"

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "server.py"]

部署选项：Railway / Render（个人项目一键部署）、AWS Lambda / Google Cloud Run（Serverless）、自建 VPS（配合 Nginx 反向代理）。监控建议：结构化请求日志、Prometheus 工具调用指标、Sentry 错误告警、健康检查接口。版本管理须声明 MCP 协议版本，采用向后兼容的工具升级策略。

需求：让 AI 能搜索本地 Markdown 笔记、支持语义搜索（向量检索）、支持创建和更新笔记。

技术选型：本地向量数据库 ChromaDB / Qdrant；嵌入模型 text-embedding-3-small；文件监听 watchfiles。

• 笔记索引工具：扫描目录，分块嵌入写入向量库
• 语义搜索工具：按 query 返回 Top-K 相关片段
• 笔记写入工具：创建或追加 Markdown 文件
• 文件资源服务：通过 Resource URI 暴露笔记全文

效果演示：在 Cursor 中问「我上周记录了什么关于 MCP 的笔记？」——AI 调用 MCP 搜索工具，返回相关笔记片段。

优质社区 Server：mcp-server-filesystem（文件系统）、mcp-server-github（GitHub 仓库）、mcp-server-brave-search（网络搜索）、mcp-server-postgres（数据库）、mcp-server-slack（Slack 消息）。

2026 趋势：OpenAI、Google、Microsoft 均已宣布支持 MCP；治理权移交 Linux Foundation AAIF；MCP Marketplace 快速发展；企业级安全标准（OAuth 2.1）进入路线图。

下一步学习路径：深入学习 MCP 协议规范；开发并发布公开 MCP Server；探索 MCP + Agent 组合；贡献开源生态（Python SDK、TypeScript SDK、Inspector）。

1. 01
   确定传输模式：本地开发用 stdio；团队共享或远程 Claude Code 调用用 HTTP+SSE，在 Server 层集中管理 API Key。
2. 02
   控制台拨备云端 Mac：登录 NUKCLOUD 控制台，选择 16 GB+ 内存（多 Server 并行建议 32 GB）；见 定价页 按小时试跑。
3. 03
   安装 Python 3.12 + mcp：SSH 登录后 pip install mcp httpx pydantic；用 MCP Inspector 本地冒烟。
4. 04
   部署 HTTP Server 并暴露端口：mcp.run(host="0.0.0.0", port=8000)；配置 Bearer Token 中间件与 CORS。
5. 05
   客户端接入验证：在 Cursor .cursor/mcp.json 指向云端 URL；确认 tools/list 与 tools/call 冒烟通过。
6. 06
   launchd 常驻与固定月租：编写 LaunchAgents plist 保持 7×24 运行；试点通过后于 下单页 锁定规格。详见 NUKCLOUD 生产就绪 Runbook。

在本地笔记本或共享 VPS 跑 HTTP MCP Server 常见合盖休眠中断会话、带宽抖动导致 SSE 断连、多开发者争抢同一进程。需要稳定长连接供 Cursor Background Agents 或个人知识库 Server 7×24 服务时，NUKCLOUD 多区域裸金属 Mac / 云端 Mac 节点在独占租户边界与规格弹性上更易与 MCP 工作流对齐。