MCP Server 用什么语言开发最好？

Python（官方 mcp SDK）适合新手快速上手；TypeScript（@modelcontextprotocol/sdk）适合前端/全栈。二者协议层等价，按团队栈选择即可。

stdio 和 HTTP 传输怎么选？

本地开发、IDE 插件优先 stdio；需要多客户端共享、SaaS 部署选 HTTP + SSE（Streamable HTTP）。

Tools 和 Resources 有什么区别？

Tools 是 AI 可调用的动作（搜索、写文件、查库）；Resources 是 AI 可读取的数据源（配置、用户资料、文件内容），通过 URI 寻址。

在远程 Mac 上调试 MCP 为何要开 VNC？

浏览器自动化、钥匙串、屏幕录制等 Server 常触发 macOS TCC 权限弹窗，纯 SSH 无法点选授权，需图形会话完成验收。

从 0 开发 MCP Server：AI 工具调用全链路

01

引言：为什么 AI 需要 MCP？

大模型再强，训练数据也有截止日，无法凭空知道你的 CRM 客户、昨晚的日志或内网 API 的实时状态。业界演进路径清晰：Function Calling → Plugins → MCP。前两者多为厂商私有格式，换模型就要重写集成层；MCP 用开放协议把「AI 能发现哪些工具、如何调用」标准化，一次编写、多 Client 复用。

01
痛点：你希望 Claude / GPT 能查数据库、调 API、操作文件，但每家格式不同。
02
场景：在 Cursor 里让 AI 读你的 Markdown 笔记、在 Claude Desktop 里查 GitHub Issue。
03
承诺：本文带你从空目录到可部署 Server，含完整代码与排障表。

02

什么是 MCP？先搞懂协议再写代码

2.1 诞生背景

Anthropic 于 2024 年 11 月发布 MCP，目标是标准化 AI 与外部工具的通信，解决 N 个模型 × M 个工具 = N×M 定制适配的碎片问题。更多协议史观可参阅站内MCP 与 HTTP 类比文。

2.2 架构概览

MCP 采用 Client ↔ Server 模型：Client 在 AI 侧（Claude Desktop、Cursor）；Server 是你开发的能力提供方，通过 JSON-RPC 暴露三大核心能力：

T
Tools（工具）：AI 可调用的函数——搜索、计算、数据库查询。
R
Resources（资源）：AI 可读取的数据——文件、URL、配置流。
P
Prompts（提示词模板）：预定义、可参数化的提示片段。

2.3 通信机制

基于 JSON-RPC 2.0；传输层支持 stdio（本地子进程，Cursor / Claude Desktop 默认）与 HTTP + SSE / Streamable HTTP（远程服务）。生命周期：初始化握手 → 能力协商（initialize）→ 请求/响应 → 关闭。

2.4 与其他方案对比

维度	MCP	OpenAI Function Calling	LangChain Tools
标准化	开放协议	厂商私有	框架绑定
传输	stdio / HTTP	HTTP	HTTP
跨模型	是	否	部分
Resources / Prompts	原生支持	不支持	不支持
生态	2026 年 10,000+ Server	成熟	成熟

03

开发环境准备

3.1 选择语言

Python（官方 SDK mcp，FastMCP 装饰器简洁）推荐新手；TypeScript（@modelcontextprotocol/sdk）适合前端/全栈。本文以 Python 为主，TS 做对照。

环境搭建

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

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

3.2 项目结构

my-mcp-server/

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

3.3 调试工具

1
MCP Inspector：npx @modelcontextprotocol/inspector python server.py
2
Claude Desktop：编辑 claude_desktop_config.json 注册 Server。
3
Cursor：Settings → MCP → 添加 command + args。

04

第一个 MCP Server：Hello World

server.py · 最小可用 Server

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 后，用 Inspector 或 Cursor 配置中填入 {"command":"python","args":["/path/to/server.py"]}，刷新工具列表应看到 say_hello。

Cursor / Claude Desktop 接入要点

✓
使用绝对路径指向 server.py 与虚拟环境 Python。
✓
修改代码后需重启 MCP 连接或重开 Cursor 窗口。
✓
在对话中明确请求调用工具，验证 AI 上下文已注册。

05

Tools：开发可被 AI 调用的工具

5.1 基本结构

函数签名即文档：参数类型、返回类型、docstring 会暴露给模型做工具选择。命名用 snake_case、动词开头（search_web、read_file）。错误宜返回结构化 JSON 而非裸抛异常，便于模型自我纠错。

5.2 复杂参数（Pydantic）

带 Schema 的搜索工具

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]:
    """执行网络搜索，返回相关结果列表"""
    ...

5.3 五个实用工具清单

工具	用途	注意点
计算器	数学表达式求值	用 ast.literal_eval 或安全解析库，禁 eval
文件读写	读/写本地文件	白名单目录、路径规范化防穿越
HTTP 请求	调外部 API	超时、重试、响应大小上限
数据库查询	只读 SQL	参数化查询、禁止 DDL
时间工具	当前时间、时区转换	返回 ISO 8601 便于模型解析

5.4 异步工具

async fetch_url

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

5.5 错误处理最佳实践

!
网络 / IO 操作设置超时（建议 15–30s）。
!
敏感操作做权限校验（API Key、允许路径）。
!
返回 {"error": "...", "hint": "..."} 帮助模型重试。

06

Resources：让 AI 读取动态内容

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:
    """根据用户 ID 返回用户资料"""
    return json.dumps(db.query_user(user_id))

资源类型包括：文本（text/plain、application/json）、二进制（图片、PDF）、流式（实时行情）。实战可做文件系统 Server：列出目录、读取文件、可选订阅文件变化。

07

Prompts：可复用的提示词模板

MCP Prompt 是预定义提示片段，支持动态参数注入，提升团队提示词一致性与可维护性。

代码审查 Prompt 模板

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} 代码：
1. 质量与可读性  2. Bug 与安全隐患  3. 性能优化

```{language}
{code}
```""")
    )]

可定义含 user + assistant 多轮模板，用于面试模拟、调试助手等场景。Client 调用 prompts/get 获取填充后的消息链。

08

进阶：HTTP 传输模式（远程 MCP Server）

特性	stdio	HTTP + SSE
部署	本地进程	远程服务器
延迟	极低	依赖网络
多客户端	不支持	支持
场景	IDE 本地工具	SaaS / 团队共享

Streamable HTTP 模式

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

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

生产环境需加：Bearer Token / API Key 中间件、CORS 白名单、请求频率限制。勿将未鉴权的 HTTP MCP 直接暴露公网。

09

调试与测试

9.1 MCP Inspector

启动 Inspector 可图形化测试 tools/list、tools/call、查看 JSON-RPC 日志、模拟错误场景。

9.2 单元测试（pytest + ClientSession）

test_calculator_tool

@pytest.mark.asyncio
async def test_calculator_tool():
    server_params = StdioServerParameters(command="python", args=["server.py"])
    async with stdio_client(server_params) 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"

9.3 常见错误排查

错误	原因	解决
工具未出现	配置路径错误	检查 config.json 绝对路径
JSON 序列化失败	返回类型不支持	转 str 或 dict
超时断开	工具执行慢	异步 + 超时控制
权限拒绝	文件路径受限	配置允许目录 / VNC 点 TCC

10

生产部署

10.1 Docker 容器化

Dockerfile

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

10.2 云服务选型

•
Railway / Render：个人项目一键部署。
•
AWS Lambda / Cloud Run：Serverless，注意冷启动与 stdio 限制。
•
自建 VPS + Nginx：反向代理 + TLS + 限流。

10.3 可观测性

结构化请求日志、Prometheus 工具调用指标、Sentry 错误告警、/health 健康检查。声明 MCP 协议版本，工具升级保持向后兼容。

11

实战：个人知识库 MCP Server

需求：让 AI 搜索本地 Markdown 笔记、语义检索、创建/更新笔记。在 Cursor 中问：「我上周记录了什么关于 MCP 的笔记？」

技术选型

组件	推荐
向量库	ChromaDB / Qdrant（本地）
嵌入模型	text-embedding-3-small
文件监听	watchfiles 增量索引

核心 Tools

1
index_notes：扫描目录建立向量索引。
2
semantic_search：按语义返回相关片段。
3
write_note：创建或追加 Markdown。
4
Resource：notes://{path} 直接读取单篇笔记。

效果：AI 调用 semantic_search 召回片段后综合回答，比把整个笔记库塞进上下文省 Token 且更准确。

12

MCP 生态与 2026 展望

优质开源 Server 推荐

→
mcp-server-filesystem — 文件系统操作
→
mcp-server-github — GitHub 仓库
→
mcp-server-brave-search — 网络搜索
→
mcp-server-postgres — 数据库查询
→
mcp-server-slack — Slack 消息

2026 年 Cursor、Claude Desktop、OpenAI、Google Gemini、Microsoft 均已支持或完成 MCP 接入；MCP Marketplace 与企业级安全标准（OAuth 2.1、审计）持续完善。官方文档：modelcontextprotocol.io；Python SDK：github.com/modelcontextprotocol/python-sdk。

落地五步（含远程 Mac 验收）

1
选定 Host（Cursor / Claude Desktop）并确认 2026 版本原生支持 MCP。
2
本地 stdio 开发 Server，Inspector 验证 tools/list。
3
注册到 Cursor MCP 配置，用 Hello World 工具冒烟测试。
4
涉及浏览器、钥匙串、屏幕录制的 Server，在 macOS 图形会话完成 TCC 授权（纯 SSH 无法点选）。
5
Docker 部署 HTTP 模式，加鉴权与监控后上线；与站内Agent Skill、浏览器 MCP文互链。

13

FAQ

Python（mcp + FastMCP）上手最快；TypeScript（@modelcontextprotocol/sdk）适合已有 Node 栈的团队。协议层等价。

IDE 本地开发优先 stdio；需多用户共享、SaaS 交付选 HTTP + SSE / Streamable HTTP，并务必加鉴权。

Tools 执行动作（写库、发请求）；Resources 提供只读数据（配置、文件内容），通过 URI 模板寻址。

浏览器 DevTools MCP、高权限文件操作、钥匙串与屏幕录制会触发 macOS TCC 弹窗。纯 SSH 无法点「始终允许」，需 VNC 图形会话与 Host 同机验收。

结语

MCP 是 AI 工具化的标准协议——掌握从 Hello World 到生产部署的全链路，是 2026 年 AI 工程师的核心竞争力之一。你打算用 MCP 开发什么工具？欢迎在实践后复盘自己的 Server 设计。

隐性成本往往不在写代码，而在运行环境：Windows 主力机 + 云端 Mac 混跑 Cursor MCP 时，权限弹窗、Python 虚拟环境与 Inspector 日志要在同一台机器的桌面会话里交叉核对；自购 Mac mini 则要承担睡眠、系统更新与折旧，8GB 内存在向量索引 + 多 Server 并发时也容易吃满。

若你希望按小时验证 MCP 工具链、又要在与 Cursor 同机的图形界面里完成 TCC 与 Inspector 验收，可通过 VNCMac 租用远程 Mac：下方主按钮进入购买页；需要对比套餐时先浏览首页。

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