Skip to main content
Glama
yunhai-dev

exec-dir-mcp

by yunhai-dev
OverviewSchemaRelated ServersScoreDiscussions
Python

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

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYes要执行的命令（shell 命令）
timeoutNo超时时间（秒），默认30秒
working_dirNo工作目录的路径（可选，默认: /app）

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. Executing arbitrary shell commands is a powerful, potentially destructive operation, yet the description doesn't disclose side effects, permissions required, whether commands run as privileged user, or any safety caveats. This is a significant gap for a command execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely brief (one sentence), which is efficient, but at the cost of substance. It's front-loaded with the core purpose and the default directory. Minimal waste, but oversimplified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a shell command execution tool with no annotations and no output schema, the description is inadequate. It doesn't describe return values/output capture, exit code handling, whether stderr/stdout are returned, or error behavior under failures. A command runner needs substantially more behavioral documentation for an agent to use it safely and correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all three parameters (command, timeout, working_dir) are documented in the schema. However, the description adds essentially no meaning beyond the schema—it only restates the default working directory. It doesn't clarify timeout semantics (what happens on timeout), command syntax expectations, or how working_dir interacts with the default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description accurately states it executes commands in a specified folder, which conveys the basic verb+resource purpose. However, it lacks a specific action verb beyond 'execute' and there are no sibling tools to differentiate against, so it's clear but minimal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, and there are no sibling tools to reference. It doesn't mention when command execution is appropriate, security considerations, or scenarios where this tool would be the right choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.0.2
    • First observedexecute_command
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.5/5.0
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
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Shell MCP Server

    odysseus0
    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

  • Simple Subprocess MCP Server

    yonaka15
    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
    -

  • Shell Server

    sergio-deras
    F
    license
    Not graded
    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.
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yunhai-dev/exec-dir-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server