使用说明

MCP服务器模板

使用FastMCP和Python构建模型上下文协议（MCP）服务器的模板。

概述

此模板为创建MCP服务器提供了最低限度的基础，这些服务器可以向Claude和其他AI助手公开工具和资源。该服务器使用FastMCP构建，FastMCP是一个简化MCP服务器开发的Python框架。

特性

使用FastMCP进行简单的MCP服务器设置
可流式HTTP传输（在 127.0.0.1:5555)
示例工具实现(add 功能）
现代Python依赖管理 uv
黑色代码格式化

快速开始

安装依赖项:
```
uv sync
```
运行服务器:
```
uv run main.py
```
服务器将于启动 http://127.0.0.1:5555 使用流式HTTP传输。

发展

添加工具

使用注册工具 @mcp.tool 装饰师：

@mcp.tool
def your_tool(param: str) -> str:
    """Tool description"""
    return f"Result: {param}"

命令

安装依赖项: uv sync
添加依赖项: uv add <package>
格式代码: uv run black .
运行服务器: uv run main.py

依赖项

fastmcp （>=2.11.3）：核心MCP服务器框架
python dotenv （>=1.1.1）：环境变量管理
黑色（>=25.1.0）：代码格式（开发依赖性）

什么是MCP？

模型上下文协议（MCP）是将AI应用程序连接到外部工具和数据源的通用标准。将其视为“USB-C for AI”-它解决了N×M复杂性问题，即每个AI应用程序都需要为每个工具进行自定义集成。

核心概念

工具：AI可以调用以执行操作的函数（如API端点）
资源：人工智能可以访问的只读数据源
提示：用于常见任务的可重用交互模板
运输：STDIO（本地）、HTTP或流式HTTP连接

连接客户

此服务器使用 流式HTTP 传输，因此客户端通过HTTP连接，而不是通过STDIO生成进程。先启动服务器(uv run main.py)，然后从您的客户端连接。

克劳德代码（CLI）

Claude Code原生支持流式HTTP。在以下位置注册服务器：

claude mcp add --transport http your-server-name http://127.0.0.1:5555/mcp

克劳德桌面版

克劳德桌面 claude_desktop_config.json 做不本机支持Streamable HTTP——它只生成STDIO服务器。使用 mcp-remote 将STDIO代理桥接到HTTP端点：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "your-server-name": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:5555/mcp"]
    }
  }
}

配置后：

确保服务器正在运行(uv run main.py)
完全重新启动克劳德桌面
您的服务器工具将出现在界面中
让克劳德使用你的工具进行测试

其他客户

原生支持Streamable HTTP的客户端（游标、MCP检查器、自定义客户端）可以直接连接到 http://127.0.0.1:5555/mcp 没有桥。

测试与调试

MCP检查员

用于测试服务器的交互式web界面。首先启动服务器，然后将Inspector指向HTTP端点：

uv run main.py  # in one terminal
npx @modelcontextprotocol/inspector  # in another, then connect to http://127.0.0.1:5555/mcp

手动测试

MCP在所有传输中使用JSON-RPC 2.0作为其消息格式。使用Streamable HTTP，您可以将这些JSON-RPC消息作为HTTP POST正文发送：

curl -X POST http://127.0.0.1:5555/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

常见问题

服务器必须正在运行 在客户端可以连接之前（HTTP传输，而不是STDIO）
端口冲突：更改 port 论点在 main.py 如果 5555 正在使用中
正确的类型提示 所有工具都需要
检查克劳德桌面日志： ~/Library/Logs/Claude/mcp.log （macOS）

高级功能

传输配置

此模板使用Streamable HTTP传输运行：

from fastmcp import FastMCP

mcp = FastMCP("Demo 🚀")

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=5555)

要切换到STDIO（用于直接生成Claude Desktop），请替换 mcp.run(...) 打电话给 mcp.run().

添加资源和提示

@mcp.resource("config://server-info")
def get_server_info() -> dict:
    """Server information resource."""
    return {
        "name": "MyServer",
        "version": "1.0.0",
        "status": "running"
    }

@mcp.prompt()
def create_summary(text: str) -> str:
    """Generate summarization prompt."""
    return f"Please summarize this text:\n\n{text}\n\nSummary:"

项目结构

├── main.py          # Main server implementation
├── pyproject.toml   # Project configuration and dependencies
├── uv.lock         # Locked dependency versions
├── CLAUDE.md        # Claude Code guidance
└── README.md       # This file

资源

FastMCP文档: github/jlowin/fastmcp
MCP规范: 模型上下文协议.io
uv包管理器: 星光sh/uv
克劳德桌面版: claude.ai