cli-agent-mcp

中文文档

Unified MCP (Model Context Protocol) server for CLI AI agents. Provides a single interface to invoke Codex, Gemini, Claude, and OpenCode CLI tools.

Features

• Unified Interface: Single MCP server exposing multiple CLI agents
• GUI Dashboard: Real-time task monitoring with pywebview
• Request Isolation: Per-request execution context for safe concurrent usage
• Signal Handling: Graceful cancellation via SIGINT without killing the server
• Debug Logging: Comprehensive subprocess output capture for debugging

Screenshot

Installation

# Install from PyPI (when published)
uvx cli-agent-mcp

# Install from GitHub
uvx --from git+https://github.com/shiharuharu/cli-agent-mcp.git cli-agent-mcp

# Install from source (editable mode for development)
uvx --from /path/to/cli-agent-mcp cli-agent-mcp

# Or use pip
pip install -e .

Configuration

Configure via environment variables:

Tools

codex

Invoke OpenAI Codex CLI agent for deep code analysis and critical review.

Best for: Code review, bug hunting, security analysis

gemini

Invoke Google Gemini CLI agent for UI design and comprehensive analysis.

Best for: UI mockups, image analysis, requirement discovery, full-text analysis

claude

Invoke Anthropic Claude CLI agent for code implementation.

Best for: Feature implementation, refactoring, code generation

opencode

Invoke OpenCode CLI agent for full-stack development.

Best for: Rapid prototyping, multi-framework projects

Permission Levels

Debug Mode

Enable debug mode to get detailed execution information:

# Enable debug info in responses
export CAM_DEBUG=true

# Enable detailed log file
export CAM_LOG_DEBUG=true

When CAM_LOG_DEBUG=true, logs are written to:

/tmp/cli-agent-mcp/cam_debug_YYYYMMDD_HHMMSS.log

Debug output includes:

• Full subprocess command
• Complete stdout/stderr output
• Return codes
• MCP request/response summaries

MCP Configuration

Add to your MCP client configuration (e.g., Claude Desktop claude_desktop_config.json):

Basic Configuration

{
  "mcpServers": {
    "cli-agent-mcp": {
      "command": "uvx",
      "args": ["cli-agent-mcp"]
    }
  }
}

Install from GitHub

{
  "mcpServers": {
    "cli-agent-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/shiharuharu/cli-agent-mcp.git",
        "cli-agent-mcp"
      ]
    }
  }
}

With Debug Mode

{
  "mcpServers": {
    "cli-agent-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/shiharuharu/cli-agent-mcp.git",
        "cli-agent-mcp"
      ],
      "env": {
        "CAM_DEBUG": "true",
        "CAM_LOG_DEBUG": "true"
      }
    }
  }
}

Disable GUI

{
  "mcpServers": {
    "cli-agent-mcp": {
      "command": "uvx",
      "args": ["cli-agent-mcp"],
      "env": {
        "CAM_GUI": "false"
      }
    }
  }
}

Limit Available Tools

{
  "mcpServers": {
    "cli-agent-mcp": {
      "command": "uvx",
      "args": ["cli-agent-mcp"],
      "env": {
        "CAM_TOOLS": "claude,gemini"
      }
    }
  }
}

Project Structure

cli-agent-mcp/
 shared/                  # Source of truth (for distribution)
    gui/
    invokers/
    parsers/
 src/cli_agent_mcp/       # Main package
    shared/              #  Synced copy (do not edit directly)
    server.py
    config.py
    gui_manager.py
 tests/
 shared_sync.sh

Important: Never edit src/cli_agent_mcp/shared/ directly. Always edit shared/ and run the sync script.

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Sync shared modules (runs tests first)
./shared_sync.sh

License

MIT