MCP Simple Server

MCP简单服务器

具有流式HTTP传输的模型上下文协议服务器的最小参考实现。按照官方Anthropic MCP规范2025-06-18使用FastMCP构建。构建远程MCP服务器的完美起点。

🎯 目的

该项目为想要以下目的的开发人员提供了一个简单、有据可查的参考：

• 构建他们的第一个MCP服务器
• 将MCP服务器部署到云平台（Railway、Heroku、Render）
• 了解MCP协议实现
• 为更复杂的MCP解决方案奠定基础

特性

• ✅ 两个数学工具: add 和 multiply 函数
• ✅ 可流式HTTP传输：支持SSE的现代MCP协议
• ✅ 会话管理：正确的MCP初始化流程
• ✅ 远程部署：铁路、Heroku、渲染部署配置
• ✅ 自动化测试：完整的协议验证和调试工具
• ✅ Claude桌面集成：已准备好集成AI助手
• ✅ 参考实现：记录良好的学习代码

快速开始

地方发展

git clone https://github.com/oleksandrsirenko/mcp-simple-server.git
cd mcp-simple-server
uv sync
source .venv/bin/activate
python main.py

服务器启动时间： http://localhost:8000/mcp/

测试服务器

python test_server.py

预期产量：

🧪 Starting MCP Server Tests
✅ Initialize successful - Server: Simple Server
✅ Initialized notification sent
✅ Found 2 tools: add, multiply  
✅ Add tool returned correct result
✅ Multiply tool returned correct result
🎉 All tests passed!

可用工具

add(a, b)

将两个数字相加。

例子：

{"name": "add", "arguments": {"a": 25, "b": 17}}
→ Returns: 42

multiply(a, b)

将两个数字相乘。

例子：

{"name": "multiply", "arguments": {"a": 8, "b": 6}}
→ Returns: 48

使用curl进行手动测试

本地测试（开发）

用于测试在上运行的本地开发服务器 localhost:8000:

1.初始化会话

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

2.发送初始化通知

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

3.列出工具

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

4.调用添加工具

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add","arguments":{"a":25,"b":17}}}'

远程测试（生产）

为了测试部署的服务器，请替换 localhost:8000 使用您的部署URL：

# Example with Railway deployment
curl -X POST https://your-app.railway.app/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

备注：要进行全面的远程测试，请使用自动化测试脚本：

python test_deployment.py your-app.railway.app

部署

铁路（推荐）

1. 推送到GitHub:

   git add .
   git commit -m "ready for deployment"
   git push origin main

1. 部署到铁路:

- 首选 railway应用程序 - 点击“从GitHub仓库部署” - 选择您的存储库 - 铁路自动检测Dockerfile并部署

1. 测试您的部署:

   python test_deployment.py your-app-name.up.railway.app

1. 您的MCP URL: https://your-app.railway.app/mcp/

Heroku

heroku create your-mcp-server
git push heroku main

您的MCP URL: https://your-mcp-server.herokuapp.com/mcp/

渲染

1. 将GitHub存储库连接到Render
2. 渲染自动检测 render.yaml 和Dockerfile
3. 自动部署

您的MCP URL: https://your-service.onrender.com/mcp/

码头工人

docker build -t mcp-simple-server .
docker run -p 8000:8000 mcp-simple-server

Claude桌面集成

本地服务器配置

{
  "mcpServers": {
    "simple-server": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "/path/to/mcp-simple-server"
    }
  }
}

远程服务器配置（推荐）

对于部署到Railway、Heroku或Render的远程服务器，请使用 mcp-remote 包裹：

{
  "mcpServers": {
    "simple-server-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-app.railway.app/mcp/",
        "--allow-http",
        "--header",
        "Accept: application/json, text/event-stream"
      ]
    }
  }
}

关键配置说明：

• 使用 npx 随着 -y 标记为自动安装 mcp-remote
• 在URL中包含尾随斜线： /mcp/
• 添加 --allow-http HTTP连接标志
• 包含Accept标头以获得适当的SSE支持

替代方案：直接Python代理（高级）

对于高级用户或调试目的，您可以创建自定义Python代理：

{
  "mcpServers": {
    "simple-server-proxy": {
      "command": "python",
      "args": ["claude_mcp_proxy.py"],
      "cwd": "/path/to/mcp-simple-server"
    }
  }
}

备注：这需要 claude_mcp_proxy.py 脚本来自存储库，主要用于调试目的。使用 mcp-remote 用于生产。

配置文件位置：

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

与克劳德一起测试

整合后，问克劳德：

• “你能给我加42和18吗？”
• “7乘以9是多少？”
• “你们有什么工具？”

Claude将使用您的MCP服务器进行计算！ 🎉

发展

添加新工具

@mcp.tool()
def subtract(a: float, b: float) -> float:
    """Subtract two numbers"""
    return a - b

@mcp.tool()
def divide(a: float, b: float) -> float:
    """Divide two numbers"""
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

环境变量

• HOST：服务器主机（默认值：127.0.0.1，部署时使用0.0.0.0）
• PORT：服务器端口（默认值：8000，Railway会自动设置此端口）

HOST=0.0.0.0 PORT=3000 python main.py

注意：对于铁路部署，FastMCP将自动绑定到 0.0.0.0:$PORT.

项目结构

mcp-simple-server/
├── main.py                    # MCP server (~25 lines)
├── test_server.py             # Local server tests (~300 lines)
├── test_deployment.py         # Remote deployment tests
├── test_host_binding.py       # Host binding tests
├── test_proxy_script.py       # Proxy testing script
├── test_streamable_app.py     # Streamable HTTP tests
├── test_tool_verification.py  # Tool verification tests
├── debug_railway_server.py    # Railway debugging utilities
├── debug_fastmcp.py           # FastMCP debugging utilities
├── claude_mcp_proxy.py        # Claude Desktop proxy (optional)
├── start.sh                   # Shell startup script
├── pyproject.toml             # Project configuration
├── README.md                  # This documentation
├── uv.lock                    # Dependency lock file
├── .gitignore                 # Git ignore patterns
├── .python-version            # Python version specification
├── Dockerfile                 # Docker deployment
├── railway.toml               # Railway configuration
├── Procfile                   # Heroku configuration
└── render.yaml                # Render configuration

建筑

• FastMCP：Anthropic的高层MCP实施
• 流式HTTP：支持SSE流媒体的现代传输
• 会话管理：具有会话ID的有状态连接
• JSON-RPC 2.0：消息交换的标准协议
• 第2025-06-18号议定书：最新MCP规范
• 端口8000：默认FastMCP服务器端口（可通过port env var配置）

技术细节

服务器实现

• 框架：FastMCP（官方人类学图书馆）
• 运输：带有服务器发送事件的流式HTTP
• 协议：MCP 2025-06-18规范
• 依赖项: httpx>=0.28.1, mcp>=1.9.4

MCP协议流

1. 客户端发送 initialize 请求
2. 服务器以功能和会话ID进行响应
3. 客户端发送 initialized 通知
4. 正常操作开始（工具/列表、工具/调用等）

工具响应格式

工具返回简单的Python值（float、int、str），FastMCP会自动将其包装成正确的MCP响应格式。

故障排除

服务器无法启动

# Check if port is in use
lsof -i :8000

# Try different port
PORT=3000 python main.py

MCP协议错误

# Run automated test
python test_server.py

# Check server logs for detailed errors

克劳德桌面未连接

1. 验证JSON配置语法 -使用JSON验证器
2. 检查服务器URL可访问性 -测试用 curl 或浏览器
3. 重新启动克劳德桌面 配置更改后
4. 确保MCP端点路径正确 -使用 /mcp/ 带有尾随斜线
5. 使用 mcp-remote 用于远程服务器 -不要使用 curl 用于远程连接

测试远程部署

使用提供的脚本测试部署的服务器：

# Test your deployed server (replace with your URL)
python test_deployment.py your-app.railway.app

# Or with full URL
python test_deployment.py https://your-app.railway.app

这将对您的远程服务器运行完整的MCP协议测试套件。

常见问题

• 端点错误：使用 /mcp/ （带尾随斜线）
• 缺少标题：包括所有必需的MCP标题
• 会话管理：必须发送 initialized 通知后 initialize
• 远程连接：使用 mcp-remote，不 curl 克劳德桌面
• 端口绑定：使用 0.0.0.0:$PORT 对于部署，不是 127.0.0.1

依赖项

dependencies = [
    "httpx>=0.28.1",   # HTTP client for testing
    "mcp>=1.9.4",      # Official Anthropic MCP library
]

该项目使用：

• 主控程序：官方Anthropic MCP Python SDK
• httpx：用于自动测试的现代HTTP客户端
• python：需要Python>=3.10

贡献

1. 分叉存储库
2. 进行更改
3. 运行测试： python test_server.py
4. 测试部署： python test_deployment.py your-test-url
5. 确保所有测试通过
6. 提交拉取请求

许可证

MIT许可证

资源

• MCP规范2025-06-18
• FastMCP文档
• 克劳德桌面
• 铁路部署
• 渲染部署
• mcp远程包