MCP UV HTTP执行器
一个安全的2服务器MCP架构，用于使用 uv 通过HTTP通信，旨在消除子流程冲突并提供干净的关注点分离。
🏗️ 架构概述
Claude Desktop
↓ STDIO/MCP Protocol
MCP HTTP Client (mcp_http_client.py)
↓ HTTP Requests
Execution Server (execution_server.py)
↓ subprocess
UV Runtime → Python Scripts
↓
Working Directory Sandbox为什么是两台服务器？
- 🚫 无子流程冲突：HTTP通信消除了MCP和脚本执行之间的stdio冲突
- 🎯 清洁分离：MCP协议处理与脚本执行分离
- 🐛 易于调试：独立测试每个组件，明确错误边界
- 📈 可扩展的：执行服务器可以移动到不同的主机，在客户端之间共享
- 🔒 安全：由执行服务器控制的工作目录沙盒
🚀 快速开始
1.安装
# Clone the repository
git clone
cd mcp-uv-http-executor
# Install UV if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh2.设置您的工作目录
# Create a directory for your Python scripts
mkdir my_python_scripts
cd my_python_scripts
# Create a test script
echo 'print("Hello from UV HTTP MCP!")' > hello.py
echo 'print("Current time:", __import__("datetime").datetime.now())' > time_test.py3.启动服务器
终端1：启动执行服务器 （控制工作目录）
# IMPORTANT: Start from your scripts directory!
cd my_python_scripts
uv run ../execution_server.py
# You should see:
# [START] Script Execution Server
# [DIR] Working directory: /path/to/my_python_scripts
# [READY] Ready to execute Python scripts!终端2：启动MCP客户端 （目录不重要）
# Can be started from anywhere
uv run mcp_http_client.py4.配置克劳德桌面
添加到您的Claude Desktop配置中：
{
"mcpServers": {
"uv_http_executor": {
"command": "uv",
"args": ["run", "/full/path/to/mcp_http_client.py"]
}
}
}5.测试一下！
打开克劳德桌面并尝试：
- “执行hello.py脚本”
- “运行time_test.py并显示输出”
- “检查执行服务器是否正在运行”
🛠️ 可用工具
执行Python脚本
execute_python_script(script_path: str, timeout: int = 30)使用可配置的超时（最大120秒）执行工作目录中的任何Python脚本。
检查服务器状态
check_execution_server()验证执行服务器是否正在运行且健康。
测试脚本
test_hello_world_http(timeout: int = 30)
test_minimal_http(timeout: int = 10)用于验证设置的内置测试脚本。
架构信息
get_http_server_info()获取有关2服务器架构的详细信息。
📁 工作目录配置
⚠️ 重要：工作目录由控制 从哪里开始 execution_server.py!
# ✅ CORRECT: Start execution server in scripts directory
cd /path/to/your/scripts
uv run /path/to/execution_server.py
# ❌ WRONG: Start execution server elsewhere and expect it to find scripts
cd /some/other/path
uv run execution_server.py # Scripts won't be found!执行服务器使用 Path.cwd() 作为工作目录，因此：
- 所有脚本路径都与启动执行服务器的位置相关
- 阻止路径遍历（否
../允许） - 仅
.py可以执行文件 - MCP客户端位置不影响脚本执行
🔧 配置
环境变量
执行服务器：
export EXECUTION_PORT=8080 # HTTP server port (default: 8080)
export EXECUTION_HOST=127.0.0.1 # HTTP server host (default: 127.0.0.1)
export MAX_SCRIPT_TIMEOUT=120 # Maximum script timeout (default: 120)MCP客户端：
export EXECUTION_SERVER_URL=http://127.0.0.1:8080 # Execution server URL
export MCP_HTTP_TIMEOUT=10 # HTTP timeout buffer (default: 10)支持的脚本类型
执行服务器自动处理不同的脚本类型：
- 独立脚本：使用标准库的基本Python脚本
- PEP 723脚本：具有内联依赖关系的脚本：
#!/usr/bin/env -S uv run
# /// script
# dependencies = ["requests", "pandas"]
# ///
import requests- 项目脚本：目录中的脚本
pyproject.toml或uv.lock
🐛 故障排除
常见问题
“无法连接到执行服务器”
# Check if execution server is running
curl http://127.0.0.1:8080/health
# If not running, start it:
cd your_scripts_directory
uv run execution_server.py“脚本路径无效”或“找不到脚本”
# Check working directory of execution server
# Look for this line in execution server output:
# [DIR] Working directory: /current/working/directory
# Make sure your script is in that directory:
ls -la /current/working/directory/your_script.py端口8080已在使用中
# Find what's using the port
lsof -i :8080
# Kill the process or change port
export EXECUTION_PORT=8081
uv run execution_server.py调试模式
使用详细输出启动执行服务器：
# The execution server already provides detailed logging
uv run execution_server.py
# Watch for [EXEC] messages showing command execution直接测试HTTP通信：
# Test execution server directly
curl -X POST http://127.0.0.1:8080/execute \
-H "Content-Type: application/json" \
-d '{"script_path": "hello.py", "timeout": 10}'📋 项目结构
mcp-uv-http-executor/
├── README.md # This file
├── SPECS.md # High-level specifications
├── execution_server.py # HTTP execution server (FastAPI)
├── mcp_http_client.py # MCP client server (FastMCP)
└── specs/ # Detailed specifications
├── core-system.md # Architecture details
├── mcp-interface.md # MCP tools and interface
└── configuration.md # Deployment and configuration🔒 安全功能
- 沙盒执行：脚本只能访问工作目录中的文件
- 路径验证：防止目录遍历攻击(
../封锁） - 文件类型限制：只有
.py可以执行文件 - 超时保护：脚本在可配置超时后终止
- 进程隔离：每个脚本都在自己的子进程中运行
- 安全环境：传递给脚本的环境变量有限
🚀 生产部署
系统化服务
创建 /etc/systemd/system/mcp-execution-server.service:
[Unit]
Description=MCP Python UV Execution Server
After=network.target
[Service]
Type=simple
User=mcp-executor
Group=mcp-executor
WorkingDirectory=/opt/scripts # Your scripts directory
ExecStart=/usr/local/bin/uv run /opt/mcp-uv-executor/execution_server.py
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target启动服务：
sudo systemctl enable mcp-execution-server
sudo systemctl start mcp-execution-serverDocker部署
FROM python:3.11-slim
RUN pip install uv
WORKDIR /app/scripts
COPY execution_server.py /app/
VOLUME ["/app/scripts"]
EXPOSE 8080
CMD ["uv", "run", "/app/execution_server.py"]🧪 开发与测试
运行测试
# Create test environment
mkdir test_scripts
cd test_scripts
# Create test files
echo 'print("Hello World!")' > hello.py
echo 'import sys; print("Args:", sys.argv[1:])' > args_test.py
echo 'import time; time.sleep(2); print("Done")' > slow_test.py
# Start execution server
uv run ../execution_server.py &
# Test with MCP inspector
mcp dev ../mcp_http_client.py集成测试
# Test HTTP API directly
curl -X POST http://127.0.0.1:8080/execute \
-H "Content-Type: application/json" \
-d '{"script_path": "hello.py", "timeout": 10}'
# Test MCP tools
echo '{"method": "tools/call", "params": {"name": "check_execution_server"}}' | \
uv run mcp_http_client.py📚 文档
🤝 贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 在两台服务器都运行的情况下进行测试
- 提交拉取请求
📄 许可证
MIT许可证-有关详细信息，请参阅许可证文件。
🙋♂️ 支持
对于问题和疑问：
- 执行服务器日志 - MCP客户端输出 - 重现步骤
______________________________________________________________________
关键要点：这种2服务器架构消除了困扰单服务器MCP实现的stdio冲突，同时为Python脚本执行提供了一个干净、可调试和可扩展的解决方案！ 🎉