Python 远程 MCP Server Demo

基于官方 MCP Python SDK 的 FastMCP， 使用 Streamable HTTP 传输实现的远程 MCP Server，可被任意 MCP 客户端（如 Cursor）远程连接。

目录结构

.
├── server.py            # 远程 MCP Server（工具 / 资源 / 提示 / 进度 / 补全）
├── client.py            # 基础测试客户端
├── client_advanced.py   # 进阶客户端（进度 + 日志 + 自动补全）
├── curl_test.sh         # 用 curl 测试的脚本
├── requirements.txt     # 依赖
└── README.md

环境要求

• Python 3.10+（本项目使用 3.11）

安装

python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

启动 Server

venv/bin/python server.py

默认监听 http://0.0.0.0:8000/mcp。可用环境变量调整：

MCP_HOST=0.0.0.0 MCP_PORT=9000 venv/bin/python server.py

运行测试客户端

另开一个终端：

venv/bin/python client.py                       # 基础：工具 / 资源 / 提示
venv/bin/python client_advanced.py              # 进阶：进度 + 日志 + 自动补全
venv/bin/python client.py http://127.0.0.1:9000/mcp

也可以用 curl 脚本（依赖 curl、jq）：

./curl_test.sh                                  # 默认 http://127.0.0.1:8000/mcp
./curl_test.sh http://127.0.0.1:9000/mcp

Server 能力

类型	名称	说明
工具	add(a, b)	求和
工具	now(tz_offset_hours=8)	返回当前时间（默认东八区）
工具	fetch_url_title(url)	抓取网页标题（异步示例）
工具	long_task(steps)	长任务，实时上报进度(progress)与日志(logging)
资源	config://app	静态配置
资源	greeting://{name}	动态参数资源
提示	summarize(text)	生成总结提示
补全	greeting://{name} 的 name	按前缀返回候选名字（completion）

进度 + 日志（long_task）

long_task 通过 ctx: Context 在执行中实时推送进度和日志。客户端注册回调即可接收：

async def on_log(params):      # 接收 ctx.info/debug 的日志
    print(params.level, params.data)

async def on_progress(progress, total, message):  # 接收进度
    print(f"{progress}/{total} {message}")

async with ClientSession(read, write, logging_callback=on_log) as session:
    await session.call_tool("long_task", {"steps": 5}, progress_callback=on_progress)

stateless_http 注意：无状态模式下不能直接用 ctx.report_progress()， 因为它未携带 related_request_id，进度通知无法关联到当前请求的 SSE 流而被丢弃。 本 demo 在 _report_progress() 中改为直接调用 session.send_progress_notification(...) 并显式传入 related_request_id=ctx.request_id。日志 ctx.info/debug 不受影响（SDK 已自动携带）。

自动补全（completion）

用 @mcp.completion() 注册全局补全处理器，为资源模板/提示的参数提供候选：

comp = await session.complete(
    ResourceTemplateReference(type="ref/resource", uri="greeting://{name}"),
    argument={"name": "name", "value": "小"},
)
print(comp.completion.values)   # => ['小明', '小红']

在 Cursor 中连接

在 ~/.cursor/mcp.json（或项目 .cursor/mcp.json）中添加：

{
  "mcpServers": {
    "demo-remote": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

说明

• stateless_http=True：每个请求独立、无会话状态，便于远程部署和水平扩展。
• 生产部署可放在 Nginx/网关之后，并自行实现鉴权（如校验 Authorization 头）。