Claude Code Mcp Enhanced

🤖 Claude Code MCP Server

> Want to get started quickly? Check out our [QUICKSTART.md](QUICKSTART.md) guide!

> This project is a fork of steipete/claude-code-mcp with enhanced orchestration capabilities, reliability improvements, and additional documentation.

An enhanced Model Context Protocol (MCP) server that allows running Claude Code in one-shot mode with permissions bypassed automatically. This server includes advanced task orchestration capabilities, robust error handling, and a "boomerang pattern" for breaking complex tasks into manageable subtasks.

Did you notice that standard AI assistants sometimes struggle with complex, multi-step edits or operations? This server, with its powerful unified claude_code tool and enhanced reliability features, aims to make Claude a more direct and capable agent for your coding tasks.

🔍 Overview

This MCP server provides powerful tools that can be used by LLMs to interact with Claude Code. When integrated with Claude Desktop or other MCP clients, it allows LLMs to:

• Run Claude Code with all permissions bypassed (using --dangerously-skip-permissions)
• Execute Claude Code with any prompt without permission interruptions
• Access file editing capabilities directly
• Execute complex multi-step operations with robust error handling and retries
• Orchestrate tasks through specialized agent roles using the boomerang pattern
• Maintain reliable execution through heartbeat mechanisms to prevent timeouts

✨ Benefits

• Enhanced Reliability: Robust error handling, automatic retries, graceful shutdown, and request tracking
• Task Orchestration: Complex workflows can be broken down into specialized subtasks
• Task Automation: Convert human-readable markdown task lists into executable MCP commands automatically
• Performance Optimization: Improved execution with configuration caching and resource efficiency
• Better Monitoring: Health check API, detailed error reporting, and comprehensive logging
• Developer Experience: Hot reloading of configuration, flexible environment controls, and simplified API

Plus all the standard Claude Code benefits:

• Claude/Windsurf often have trouble editing files. Claude Code is better and faster at it.
• Multiple commands can be queued instead of direct execution. This saves context space so more important information is retained longer.
• File ops, git, or other operations don't need costly models. Claude Code is cost-effective if you sign up for Anthropic Max.
• Claude has wider system access, so when standard assistants are stuck, just ask them to "use claude code" to unblock progress.

📝 Prerequisites

• Node.js v20 or later (Use fnm or nvm to install)
• Claude CLI installed locally (run it and call /doctor) and -dangerously-skip-permissions accepted.

💾 Installation & Usage

You can install and use this MCP server in three different ways:

🚀 Method 1: Via GitHub URL (Recommended)

The most flexible method is to install directly from GitHub using npx. This always fetches the latest version from the repository.

Add the following to your .mcp.json file:

{
  "mcpServers": {
    "claude-code-mcp-enhanced": {
      "command": "npx",
      "args": [
        "github:grahama1970/claude-code-mcp-enhanced"
      ],
      "env": {
        "MCP_CLAUDE_DEBUG": "false",
        "MCP_HEARTBEAT_INTERVAL_MS": "15000",
        "MCP_EXECUTION_TIMEOUT_MS": "1800000"
      }
    }
  }
}

📦 Method 2: Via npm Package

If the package is published to npm, you can install it using the npm package name:

{
  "mcpServers": {
    "claude-code-mcp-enhanced": {
      "command": "npx",
      "args": [
        "-y",
        "@grahama1970/claude-code-mcp-enhanced@latest"
      ],
      "env": {
        "MCP_CLAUDE_DEBUG": "false",
        "MCP_HEARTBEAT_INTERVAL_MS": "15000",
        "MCP_EXECUTION_TIMEOUT_MS": "1800000"
      }
    }
  }
}

🔧 Method 3: Local Installation

For development or testing purposes, you can run the server from a local installation:

1. Clone the repository:

``bash git clone https://github.com/grahama1970/claude-code-mcp-enhanced.git cd claude-code-mcp-enhanced ``

1. Install dependencies and build:

``bash npm install npm run build ``

1. Configure your .mcp.json file to use the local server:

{
  "mcpServers": {
    "claude-code-mcp-enhanced": {
      "command": "node",
      "args": [
        "/path/to/claude-code-mcp-enhanced/dist/server.js"
      ],
      "env": {
        "MCP_CLAUDE_DEBUG": "false",
        "MCP_HEARTBEAT_INTERVAL_MS": "15000",
        "MCP_EXECUTION_TIMEOUT_MS": "1800000"
      }
    }
  }
}

🔑 Important First-Time Setup: Accepting Permissions

Before the MCP server can successfully use the claude_code tool, you must first run the Claude CLI manually once with the --dangerously-skip-permissions flag, login and accept the terms.

This is a one-time requirement by the Claude CLI.

npm install -g @anthropic-ai/claude-code

claude --dangerously-skip-permissions

Follow the prompts to accept. Once this is done, the MCP server will be able to use the flag non-interactively.

macOS might ask for various folder permissions the first time the tool runs, and the first run may fail. Subsequent runs will work normally.

🔗 Connecting to Your MCP Client

After setting up the server, you need to configure your MCP client (like Cursor, Claude Desktop, or others that use mcp.json or mcp_config.json).

Example MCP Configuration File

Here's an example of how to add the Claude Code MCP server to your .mcp.json file:

{
  "mcpServers": {
    "Local MCP Server": {
      "type": "stdio",
      "command": "node",
      "args": [
        "dist/server.js"
      ],
      "env": {
        "MCP_USE_ROOMODES": "true",
        "MCP_WATCH_ROOMODES": "true",
        "MCP_CLAUDE_DEBUG": "false"
      }
    },
    "other-services": {
      // Your other MCP services here
    }
  }
}

MCP Configuration Locations

The configuration is typically done in a JSON file. The name and location can vary depending on your client.

Cursor

Cursor uses mcp.json.

• macOS: ~/.cursor/mcp.json
• Windows: %APPDATA%\\Cursor\\mcp.json
• Linux: ~/.config/cursor/mcp.json

Windsurf

Windsurf users use mcp_config.json

• macOS: ~/.codeium/windsurf/mcp_config.json
• Windows: %APPDATA%\\Codeium\\windsurf\\mcp_config.json
• Linux: ~/.config/.codeium/windsurf/mcp_config.json

(Note: In some mixed setups, if Cursor is also installed, these clients might fall back to using Cursor's ~/.cursor/mcp.json path. Prioritize the Codeium-specific paths if using the Codeium extension.)

Create this file if it doesn't exist.

🛠️ Tools Provided

This server exposes three primary tools:

claude_code 💬

Executes a prompt directly using the Claude Code CLI with --dangerously-skip-permissions.

Arguments:

• prompt (string, required): The prompt to send to Claude Code.
• workFolder (string, optional): The working directory for the Claude CLI execution, required when using file operations or referencing any file.
• parentTaskId (string, optional): ID of the parent task that created this task (for task orchestration/boomerang).
• returnMode (string, optional): How results should be returned: 'summary' (concise) or 'full' (detailed). Defaults to 'full'.
• taskDescription (string, optional): Short description of the task for better organization and tracking in orchestrated workflows.
• mode (string, optional): When MCPUSEROOMODES=true, specifies the Roo mode to use (e.g., "boomerang-mode", "coder", "designer", etc.).

health 🩺

Returns health status, version information, and current configuration of the Claude Code MCP server.

Example Health Check Request:

{
  "toolName": "claude_code:health",
  "arguments": {}
}

Example Response:

{
  "status": "ok",
  "version": "1.12.0",
  "claudeCli": {
    "path": "claude",
    "status": "available"
  },
  "config": {
    "debugMode": true,
    "heartbeatIntervalMs": 15000,
    "executionTimeoutMs": 1800000,
    "useRooModes": true,
    "maxRetries": 3,
    "retryDelayMs": 1000
  },
  "system": {
    "platform": "linux",
    "release": "6.8.0-57-generic",
    "arch": "x64",
    "cpus": 16,
    "memory": {
      "total": "32097MB",
      "free": "12501MB"
    },
    "uptime": "240 minutes"
  },
  "timestamp": "2025-05-15T18:30:00.000Z"
}

convert_task_markdown 📋

Converts markdown task files into Claude Code MCP-compatible JSON format.

Arguments:

• markdownPath (string, required): Path to the markdown task file to convert.
• outputPath (string, optional): Path where to save the JSON output. If not provided, returns the JSON directly.

Example Request:

{
  "toolName": "claude_code:convert_task_markdown",
  "arguments": {
    "markdownPath": "/home/user/tasks/validation.md",
    "outputPath": "/home/user/tasks/validation.json"
  }
}

Example Usage Scenarios

1. Basic Code Operation

Example MCP Request:

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nRefactor the function foo in main.py to be async.",
    "workFolder": "/path/to/project"
  }
}

2. Task Orchestration (Boomerang Pattern)

Parent Task Request:

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nOrchestrate the implementation of a new API endpoint with the following subtasks:\n1. Create database models\n2. Implement API route handlers\n3. Write unit tests\n4. Document the API",
    "workFolder": "/path/to/project"
  }
}

Subtask Request (Generated by Parent):

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nCreate database models for the new API endpoint as specified in the requirements.",
    "workFolder": "/path/to/project",
    "parentTaskId": "task-123",
    "returnMode": "summary",
    "taskDescription": "Database model creation for API endpoint"
  }
}

3. Specialized Mode Request

Example Using Roo Mode:

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Your work folder is /path/to/project\n\nCreate unit tests for the user authentication module.",
    "workFolder": "/path/to/project",
    "mode": "coder"
  }
}

🔄 Task Converter

The MCP server includes a powerful task converter tool that automatically transforms human-readable markdown task lists into fully executable MCP commands. This intelligent converter bridges the gap between how humans think about tasks and how machines execute them.

Complete Workflow

graph TD
    A["👤 User"] -->|"Create tasks.md"| B["📝 Multi-Task Markdown"]
    A -->|"Prompt Claude"| C["🤖 Claude Desktop"]
    C -->|"Use convert_task_markdown"| D["🔄 Task Converter MCP"]
    D -->|"Validate Format"| E{"Format Valid?"}
    E -->|"No"| F["📑 Error + Fix Instructions"]
    F -->|"Return to User"| A
    E -->|"Yes"| G["📋 MCP Task List"]
    G -->|"Execute Task"| H1["⚡ Claude Task #1"]
    H1 -->|"Complete"| I1["Next Task"]
    I1 -->|"Execute Task"| H2["⚡ Claude Task #2"]
    H2 -->|"Complete"| I2["Next Task"]
    I2 -->|"Execute Task"| H3["⚡ Claude Task #3"]
    H3 -->|"Complete"| I3["More Tasks"]
    I3 -->|"Execute Task"| HN["⚡ Claude Task #N"]
    HN -->|"Complete"| IN["🎉 All Tasks Completed!"]
    
    style A fill:#4A90E2,stroke:#fff,stroke-width:2px,color:#fff
    style C fill:#7C4DFF,stroke:#fff,stroke-width:2px,color:#fff
    style D fill:#00BCD4,stroke:#fff,stroke-width:2px,color:#fff
    style F fill:#FF5252,stroke:#fff,stroke-width:2px,color:#fff
    style G fill:#4CAF50,stroke:#fff,stroke-width:2px,color:#fff
    style H1 fill:#FFC107,stroke:#fff,stroke-width:2px,color:#fff
    style H2 fill:#FFC107,stroke:#fff,stroke-width:2px,color:#fff
    style H3 fill:#FFC107,stroke:#fff,stroke-width:2px,color:#fff
    style HN fill:#FFC107,stroke:#fff,stroke-width:2px,color:#fff
    style IN fill:#4CAF50,stroke:#fff,stroke-width:2px,color:#fff

Workflow Steps

1. User adds the MCP to their configuration file
2. User prompts Claude: "Use converttaskmarkdown to execute my tasks.md file"
3. The MCP automatically:

• Loads the markdown file
• Validates the format (returns errors if sections are missing)
• Converts human-readable tasks into exact executable commands
• Returns JSON that Claude Code can execute sequentially

1. Claude receives the JSON and can execute each task using the claude_code tool

Key Features

• Automatic Path Resolution: Converts generic instructions like "change directory to project" into exact executable commands with full paths
• Smart Command Translation: Transforms English instructions into precise terminal commands (e.g., "activate the virtual environment" → source .venv/bin/activate)
• MCP Protocol Compliance: Ensures all output is 100% compatible with the Model Context Protocol
• No Ambiguity: All generated commands use exact paths and executable syntax - no placeholders or generic references
• Format Validation: Enforces proper markdown structure and provides helpful error messages for incorrect formatting
• Real-time Progress Updates: Provides live progress updates during conversion showing which tasks are being processed

Convert Markdown Tasks to MCP Commands

The convert_task_markdown tool processes structured markdown files and generates MCP-compatible JSON:

Request Format:

{
  "tool": "convert_task_markdown",
  "arguments": {
    "markdownPath": "/path/to/tasks.md",
    "outputPath": "/path/to/output.json" // optional
  }
}

Response Format:

{
  "tasksCount": 5,
  "outputPath": "/path/to/output.json",
  "tasks": [
    {
      "tool": "claude_code",
      "arguments": {
        "command": "cd /project && source .venv/bin/activate\n\nTASK TYPE: Validation...",
        "dangerously_skip_permissions": true,
        "timeout_ms": 300000
      }
    }
    // ... more tasks
  ]
}

Markdown Task File Format

Task markdown files should follow this structure:

# Task 001: Task Title

## Objective
Clear description of what needs to be accomplished.

## Requirements
1. [ ] First requirement
2. [ ] Second requirement

## Tasks

### Module or Component Name
- [ ] Validate `path/to/file.py`
   - [ ] Step 1
   - [ ] Step 2
   - [ ] Step 3

The converter will:

1. Parse the markdown structure
2. Extract task metadata and requirements
3. Generate detailed prompts for each validation task
4. Include proper working directory setup
5. Add verification and completion summaries

Example Usage

1. Create a task file (tasks/api_validation.md):

# Task 001: API Endpoint Validation

## Objective
Validate all API endpoints work with real database connections.

## Requirements
1. [ ] All endpoints must use real database
2. [ ] No mock data in validation

## Core API Tasks
- [ ] Validate `api/users.py`
   - [ ] Change directory to project and activate .venv
   - [ ] Test user creation endpoint
   - [ ] Test user retrieval endpoint
   - [ ] Verify JSON responses

1. Convert to MCP tasks:

{
  "tool": "convert_task_markdown",
  "arguments": {
    "markdownPath": "/project/tasks/api_validation.md"
  }
}

1. The converter shows real-time progress:

`` [Progress] Loading task file... [Progress] Validating markdown structure... [Progress] Converting 27 validation tasks... [Progress] Task 1/27: Converting core/constants.py [Progress] Task 2/27: Converting core/arango_setup.py ... [Progress] Conversion complete! ``

1. **The converter transforms generic ins

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: grahama1970
• Source: grahama1970/claude-code-mcp-enhanced
• License: MIT

Install and usage instructions live in the source repository linked above.