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助手
- ✅ 参考实现:记录良好的学习代码
快速开始
地方发展```bash
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/`
### 测试服务器```bash
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)`
将两个数字相加。
**例子:**```json
{"name": "add", "arguments": {"a": 25, "b": 17}}
→ Returns: 42
multiply(a, b)
将两个数字相乘。
例子:```json
{"name": "multiply", "arguments": {"a": 8, "b": 6}}
→ Returns: 48
## 使用curl进行手动测试
### 本地测试(开发)
用于测试在上运行的本地开发服务器 `localhost:8000`:
#### 1.初始化会话```bash
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.发送初始化通知```bash
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.列出工具```bash
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.调用添加工具```bash
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:```bash
# 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"}}}'
备注:要进行全面的远程测试,请使用自动化测试脚本:```bash
python test_deployment.py your-app.railway.app
## 部署
### 铁路(推荐)
1. **推送到GitHub**:```bash
git add .
git commit -m "ready for deployment"
git push origin main
- 部署到铁路:
- 首选 railway应用程序
- 点击“从GitHub仓库部署”
- 选择您的存储库
- 铁路自动检测Dockerfile并部署
- 测试您的部署:```bash
python test_deployment.py your-app-name.up.railway.app
1. **您的MCP URL**: `https://your-app.railway.app/mcp/`
### Heroku```bash
heroku create your-mcp-server
git push heroku main
您的MCP URL: https://your-mcp-server.herokuapp.com/mcp/
渲染
- 将GitHub存储库连接到Render
- 渲染自动检测
render.yaml和Dockerfile - 自动部署
您的MCP URL: https://your-service.onrender.com/mcp/
码头工人```bash
docker build -t mcp-simple-server .
docker run -p 8000:8000 mcp-simple-server
## Claude桌面集成
### 本地服务器配置```json
{
"mcpServers": {
"simple-server": {
"command": "python",
"args": ["main.py"],
"cwd": "/path/to/mcp-simple-server"
}
}
}
远程服务器配置(推荐)
对于部署到Railway、Heroku或Render的远程服务器,请使用 mcp-remote 包裹:```json
{
"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代理:```json
{
"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服务器进行计算! 🎉
发展
添加新工具```python
@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会自动设置此端口)```bash
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` 请求
1. 服务器以功能和会话ID进行响应
1. 客户端发送 `initialized` 通知
1. 正常操作开始(工具/列表、工具/调用等)
### 工具响应格式
工具返回简单的Python值(float、int、str),FastMCP会自动将其包装成正确的MCP响应格式。
## 故障排除
### 服务器无法启动```bash
# Check if port is in use
lsof -i :8000
# Try different port
PORT=3000 python main.py
MCP协议错误```bash
Run automated test
python test_server.py
Check server logs for detailed errors
### 克劳德桌面未连接
1. **验证JSON配置语法** -使用JSON验证器
1. **检查服务器URL可访问性** -测试用 `curl` 或浏览器
1. **重新启动克劳德桌面** 配置更改后
1. **确保MCP端点路径正确** -使用 `/mcp/` 带有尾随斜线
1. **使用 `mcp-remote` 用于远程服务器** -不要使用 `curl` 用于远程连接
### 测试远程部署
使用提供的脚本测试部署的服务器:```bash
# 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
依赖项```toml
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
贡献
- 分叉存储库
- 进行更改
- 运行测试:
python test_server.py - 测试部署:
python test_deployment.py your-test-url - 确保所有测试通过
- 提交拉取请求
许可证
MIT许可证
资源
- MCP规范2025-06-18
- FastMCP文档
- 克劳德桌面
- 铁路部署
- 渲染部署
- mcp远程包
