MCP Hello World Server

# Claude Desktop HTTP 模式配置指南 本指南将帮助你将 MCP Hello World 服务器以 HTTP 模式添加到 Claude Desktop。 ## 🚀 快速开始 ### 步骤 1: 启动 HTTP 服务器 #### 方法一：使用启动脚本（推荐） **Windows PowerShell:** ```powershell cd C:\work\backend\python-mcp .\start_http_server.ps1 ``` **Windows 批处理:** ```cmd cd C:\work\backend\python-mcp start_http_server.bat ``` **手动启动:** ```powershell cd C:\work\backend\python-mcp python mcp_server_http.py ``` 服务器将在 `http://localhost:8000` 启动。 #### 验证服务器运行 打开浏览器访问： - 健康检查: http://localhost:8000/health - 工具列表: http://localhost:8000/tools - MCP端点: http://localhost:8000/mcp ### 步骤 2: 配置 Claude Desktop #### 找到配置文件 **Windows:** ``` %APPDATA%\Claude\claude_desktop_config.json ``` 完整路径： ``` C:\Users\<你的用户名>\AppData\Roaming\Claude\claude_desktop_config.json ``` 快速打开： ```powershell notepad "$env:APPDATA\Claude\claude_desktop_config.json" ``` #### 编辑配置文件 **如果配置文件不存在，创建它：** ```json { "mcpServers": { "hello-world": { "url": "http://localhost:8000/mcp" } } } ``` **如果配置文件已存在，添加新配置：** ```json { "mcpServers": { "existing-server": { // ... 现有配置 ... }, "hello-world": { "url": "http://localhost:8000/mcp" } } } ``` ### 步骤 3: 重启 Claude Desktop 1. **完全退出 Claude Desktop** - 关闭所有窗口 - 检查任务管理器，确保没有残留进程 2. **确保 HTTP 服务器正在运行** - 服务器必须保持运行状态 - 可以在另一个终端窗口运行服务器 3. **重新启动 Claude Desktop** 4. **测试使用** - 在 Claude 中输入：`使用hello_world工具问候张三` ## 📋 配置说明 ### HTTP 模式 vs stdio 模式 | 特性 | HTTP 模式 | stdio 模式 | |------|-----------|------------| | 连接方式 | URL | 命令行启动进程 | | 服务器状态 | 需要手动启动并保持运行 | Claude Desktop 自动管理 | | 配置格式 | `"url": "http://..."` | `"command": "python", "args": [...]` | | 适用场景 | 远程部署、多客户端共享 | 本地开发、单客户端使用 | ### 配置格式 **HTTP 模式：** ```json { "mcpServers": { "hello-world": { "url": "http://localhost:8000/mcp" } } } ``` **stdio 模式（对比）：** ```json { "mcpServers": { "hello-world": { "command": "python", "args": ["mcp_server.py"], "cwd": "C:\\work\\backend\\python-mcp" } } } ``` ### 自定义端口 如果使用非默认端口（8000），修改配置： ```json { "mcpServers": { "hello-world": { "url": "http://localhost:9000/mcp" } } } ``` 启动服务器时指定端口： ```powershell $env:PORT=9000 python mcp_server_http.py ``` ## 🔧 高级配置 ### 使用远程服务器 如果服务器部署在远程机器上： ```json { "mcpServers": { "hello-world": { "url": "https://your-server.com/mcp" } } } ``` **注意：** 远程服务器必须： - 支持 HTTPS（Claude Desktop 要求） - 可公开访问 - 实现 MCP 协议端点 ### 添加认证（如果需要） 如果服务器需要认证，可以在 URL 中包含： ```json { "mcpServers": { "hello-world": { "url": "http://localhost:8000/mcp", "headers": { "Authorization": "Bearer your-token-here" } } } } ``` ## 🧪 测试和验证 ### 1. 测试 HTTP 服务器 **健康检查：** ```powershell curl http://localhost:8000/health ``` **工具列表：** ```powershell curl http://localhost:8000/tools ``` **MCP 协议测试：** ```powershell curl -X POST http://localhost:8000/mcp ` -H "Content-Type: application/json" ` -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' ``` ### 2. 验证 Claude Desktop 连接 1. 启动 HTTP 服务器 2. 配置 Claude Desktop 3. 重启 Claude Desktop 4. 在 Claude 中尝试使用工具 ### 3. 查看日志 **HTTP 服务器日志：** - 服务器启动时会显示请求日志 - 查看终端输出了解连接状态 **Claude Desktop 日志：** - Windows: `%APPDATA%\Claude\logs\` - 查看日志文件了解连接问题 ## ❓ 故障排除 ### 问题1: Claude Desktop 无法连接到服务器 **检查清单：** - [ ] HTTP 服务器是否正在运行 - [ ] 端口是否正确（默认 8000） - [ ] URL 配置是否正确 - [ ] 防火墙是否阻止了连接 **调试方法：** ```powershell # 检查服务器是否运行 curl http://localhost:8000/health # 检查端口是否被占用 netstat -ano | findstr :8000 ``` ### 问题2: 服务器启动失败 **可能原因：** - 端口被占用 - 依赖未安装 - Python 版本不兼容 **解决方案：** ```powershell # 安装依赖 pip install -r requirements.txt # 使用不同端口 $env:PORT=9000 python mcp_server_http.py ``` ### 问题3: 工具不可用 **可能原因：** - 服务器未正确响应 MCP 协议 - Claude Desktop 未正确连接 - 需要重启 Claude Desktop **解决方案：** 1. 测试 MCP 端点是否正常响应 2. 检查服务器日志 3. 完全重启 Claude Desktop ### 问题4: 服务器自动停止 **解决方案：** - 使用后台运行（见下方） - 使用系统服务（Windows Service） - 使用 Docker 容器 ## 🔄 后台运行（可选） ### Windows: 使用后台任务 **PowerShell:** ```powershell Start-Process python -ArgumentList "mcp_server_http.py" -WindowStyle Hidden ``` **或使用 nohup（如果安装了 Git Bash）:** ```bash nohup python mcp_server_http.py > server.log 2>&1 & ``` ### 使用 Windows 服务 可以使用 `NSSM` (Non-Sucking Service Manager) 将 Python 脚本注册为 Windows 服务： ```powershell # 下载 NSSM # 安装服务 nssm install MCPHelloWorld "C:\Python\python.exe" "C:\work\backend\python-mcp\mcp_server_http.py" nssm start MCPHelloWorld ``` ## 📝 完整配置示例 ```json { "mcpServers": { "hello-world": { "url": "http://localhost:8000/mcp" }, "another-server": { "url": "https://remote-server.com/mcp", "headers": { "Authorization": "Bearer token" } } } } ``` ## 🎯 使用工具 配置成功后，在 Claude Desktop 中： ``` 使用hello_world工具问候Alice，用英文，重复3次 ``` 工具会自动通过 HTTP 调用服务器并返回结果！ ## 📚 参考 - [MCP 协议文档](https://modelcontextprotocol.io) - [Claude Desktop MCP 文档](https://claude.ai/docs/mcp) - [FastAPI 文档](https://fastapi.tiangolo.com)