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 服务器运行

基本用法

# 使用当前目录作为默认目录，允许所有目录
python -m exec_dir_mcp.main

# 指定默认目录
python -m exec_dir_mcp.main --dir /home/user/projects

# 指定默认目录和允许的目录列表
python -m exec_dir_mcp.main --dir /home/user/projects --allowed /home/user/projects --allowed /tmp

命令行参数

• --dir：默认工作目录（默认：当前目录）
• --allowed：允许执行命令的目录（可多次指定，不指定则允许所有目录）

示例

# 在项目目录中运行，允许访问项目目录和临时目录
python -m exec_dir_mcp.main \
  --dir /home/user/my-project \
  --allowed /home/user/my-project \
  --allowed /tmp

# 安全模式：只允许特定目录
python -m exec_dir_mcp.main \
  --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
• 传输协议：标准输入/输出

安全说明

1. 目录限制：强烈建议在生产环境中配置 --allowed 参数限制可访问的目录
2. 命令执行：服务器会执行传入的任意 shell 命令，请确保客户端输入的安全性
3. 超时保护：默认 30 秒超时，可通过 timeout 参数调整
4. 路径验证：自动验证目录存在性和权限

开发

运行测试

uv run pytest

代码格式化

uv run ruff format .
uv run ruff check .

许可证

MIT License

作者

YunHai yunhai@bybxbwg.fun

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

v0.1.0

• 初始版本
• 支持基本的命令执行功能
• 支持目录权限控制
• 支持超时配置