Skip to main content
Glama
exec-dir-mcp

exec-dir-mcp

by yunhai-dev

Exec Dir MCP

一个基于 Model Context Protocol (MCP) 的命令执行服务器,支持在指定目录中安全地执行命令。

功能特性

  • 🎯 安全执行:支持配置允许的目录列表,防止在未授权目录执行命令

  • 📁 灵活配置:可设置默认工作目录,支持在任意允许的目录执行命令

  • ⏱️ 超时控制:支持自定义命令执行超时时间

  • 🔄 异步执行:基于 asyncio 的异步命令执行,性能优异

  • 📊 详细日志:完整的执行日志记录,方便调试和监控

  • 🛡️ 目录验证:自动验证目录存在性和权限

Related MCP server: MCP Shell Server

安装

系统要求

  • 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

  • 传输协议:标准输入/输出

安全说明

  1. 目录限制:强烈建议在生产环境中配置 --allowed 参数限制可访问的目录

  2. 命令执行:服务器会执行传入的任意 shell 命令,请确保客户端输入的安全性

  3. 超时保护:默认 30 秒超时,可通过 timeout 参数调整

  4. 路径验证:自动验证目录存在性和权限

开发

运行测试

uv run pytest

代码格式化

uv run ruff format .
uv run ruff check .

许可证

MIT License

作者

YunHai yunhai@yhnotes.com

贡献

欢迎提交 Issue 和 Pull Request!

更新日志

v1.0.2

  • 初始版本

  • 支持基本的命令执行功能

  • 支持目录权限控制

  • 支持超时配置

  • 完善文档和配置说明

Available Tools

1 tool
execute_commandC

在指定文件夹中执行命令。默认目录: /app

Inputs: command (required), timeout, working_dir.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.5/5.0

    Scored across 1 tool

    Disambiguation4/5

    With only one tool, there is no risk of confusion or misselection between tools. The single tool has a clear, singular purpose of executing commands in a specified directory.

    Naming Consistency3/5

    With only one tool, there is no pattern to assess beyond the single name itself. 'execute_command' is a reasonable verb_noun name, but consistency cannot truly be evaluated with a single data point.

    Tool Count2/5

    A server with a single tool feels extremely thin for a directory-execution MCP server. One would expect at least listing directory contents, reading files, or inspecting the environment alongside command execution.

    Completeness2/5

    The tool provides command execution, but a directory-execution server would plausibly benefit from related operations like listing directory contents, checking working directory, or managing paths. With only execute_command, the surface is quite limited and likely to create dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that allows LLMs to execute shell commands and receive their output in a controlled manner.
      7
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that enables LLM applications to safely execute shell commands with error handling and timeout settings.
      1
      -
    • F
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables users to execute arbitrary shell commands through a terminal tool. It supports custom working directories, configurable execution timeouts, and safe command parsing using shlex.
      1
      -