Exec Dir MCP
一个基于 Model Context Protocol (MCP) 的命令执行服务器，支持在指定目录中安全地执行命令。
功能特性
- 🎯 安全执行：支持配置允许的目录列表，防止在未授权目录执行命令
- 📁 灵活配置：可设置默认工作目录，支持在任意允许的目录执行命令
- ⏱️ 超时控制：支持自定义命令执行超时时间
- 🔄 异步执行：基于 asyncio 的异步命令执行，性能优异
- 📊 详细日志：完整的执行日志记录，方便调试和监控
- 🛡️ 目录验证：自动验证目录存在性和权限
安装
系统要求
- Python >= 3.13
- uv (推荐) 或 pip
使用 uv 安装
# 克隆仓库
git clone https://github.com/yunhai-dev/exec-dir-mcp.git
cd exec-dir-mcp
# 安装依赖
uv sync
# 开发模式安装
uv pip install -e .使用 pip 安装
pip install -e .MCP 客户端配置
Claude Desktop 配置
在你的 claude_desktop_config.json 中添加以下配置：
{
"mcpServers": {
"exec-dir-mcp": {
"command": "uvx",
"args": ["exec-dir-mcp"]
}
}
}安全配置示例
基本配置（允许所有目录）：
{
"mcpServers": {
"exec-dir-mcp": {
"command": "uvx",
"args": ["exec-dir-mcp"]
}
}
}安全配置（限制可访问目录）：
{
"mcpServers": {
"exec-dir-mcp": {
"command": "uvx",
"args": [
"exec-dir-mcp",
"--dir", "/home/user/projects",
"--allowed", "/home/user/projects",
"--allowed", "/tmp"
]
}
}
}多项目工作区配置：
{
"mcpServers": {
"exec-dir-mcp": {
"command": "uvx",
"args": [
"exec-dir-mcp",
"--dir", "/workspace",
"--allowed", "/workspace/project1",
"--allowed", "/workspace/project2",
"--allowed", "/workspace/shared"
]
}
}
}其他 MCP 客户端配置
UVX 方式（推荐）
使用 uvx 直接运行（最简单，无需安装）：
{
"mcpServers": {
"exec-dir-mcp": {
"command": "uvx",
"args": [
"exec-dir-mcp",
"--dir", "/workspace",
"--allowed", "/workspace"
]
}
}
}直接命令方式
如果你已经安装了包（pip install 或 uv add），可以直接使用：
{
"mcpServers": {
"exec-dir-mcp": {
"command": "exec-dir-mcp",
"args": [
"--dir", "/workspace",
"--allowed", "/workspace"
]
}
}
}配置说明
- command:
- uvx exec-dir-mcp: 使用 uvx 直接运行（推荐，最简单） - exec-dir-mcp: 已安装包后的直接命令
- args: 启动参数
- --dir: 指定默认工作目录 - --allowed: 指定允许访问的目录（可多次使用）
配置方式对比
| 方式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
uvx exec-dir-mcp | ✅ 无需安装 | ||
| ✅ 最简单 | ❌ 需要 uv | 推荐使用 | |
exec-dir-mcp | ✅ 已安装后直接使用 | ❌ 需要先安装包 | 已在环境中安装 |
配置文件位置
- Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json - Linux: ~/.config/Claude/claude_desktop_config.json
使用方法
作为 MCP 服务器运行
基本用法
# 使用 uvx（推荐）
uvx exec-dir-mcp
# 使用已安装的命令
exec-dir-mcp
# 使用模块方式
python -m exec_dir_mcp.main
# 指定默认目录
uvx exec-dir-mcp --dir /home/user/projects
# 指定默认目录和允许的目录列表
uvx exec-dir-mcp \
--dir /home/user/projects \
--allowed /home/user/projects \
--allowed /tmp命令行参数
--dir：默认工作目录（默认：当前目录）--allowed：允许执行命令的目录（可多次指定，不指定则允许所有目录）
示例
# 在项目目录中运行，允许访问项目目录和临时目录
uvx exec-dir-mcp \
--dir /home/user/my-project \
--allowed /home/user/my-project \
--allowed /tmp
# 安全模式：只允许特定目录
uvx exec-dir-mcp \
--dir /safe/workspace \
--allowed /safe/workspace/project1 \
--allowed /safe/workspace/project2在代码中使用
import asyncio
from exec_dir_mcp.main import MCPServer
async def main():
# 创建服务器实例
server = MCPServer(
default_dir="/home/user/projects",
allowed_dirs=["/home/user/projects", "/tmp"]
)
# 运行服务器
await server.run()
asyncio.run(main())MCP 工具
execute_command
在指定目录中执行命令。
参数
command(string, 必需)：要执行的 shell 命令working_dir(string, 可选)：工作目录（默认使用配置的默认目录）timeout(integer, 可选)：超时时间，单位秒（默认：30）
返回值
{
"success": true,
"stdout": "命令标准输出",
"stderr": "命令标准错误输出",
"returncode": 0,
"working_dir": "/执行目录",
"command": "执行的命令"
}错误响应
{
"success": false,
"error": "错误描述"
}使用示例
# 通过 MCP 客户端调用
result = await client.call_tool("execute_command", {
"command": "ls -la",
"working_dir": "/home/user/projects",
"timeout": 10
})项目结构
exec-dir-mcp/
├── README.md # 项目文档
├── pyproject.toml # 项目配置
├── .gitignore # Git 忽略文件
├── .python-version # Python 版本
├── src/
│ └── exec_dir_mcp/
│ ├── __init__.py # 包初始化
│ ├── main.py # 主程序逻辑
│ └── py.typed # 类型提示标记协议支持
- MCP 版本：2024-11-05
- JSON-RPC：2.0
- 传输协议：标准输入/输出
安全说明
- 目录限制：强烈建议在生产环境中配置
--allowed参数限制可访问的目录 - 命令执行：服务器会执行传入的任意 shell 命令，请确保客户端输入的安全性
- 超时保护：默认 30 秒超时，可通过
timeout参数调整 - 路径验证：自动验证目录存在性和权限
开发
运行测试
uv run pytest代码格式化
uv run ruff format .
uv run ruff check .许可证
MIT License
作者
YunHai
贡献
欢迎提交 Issue 和 Pull Request！
更新日志
v1.0.2
- 初始版本
- 支持基本的命令执行功能
- 支持目录权限控制
- 支持超时配置
- 完善文档和配置说明