Claude Code MCP Enhanced

🤖 Claude Code MCP Server

Want to get started quickly? Check out our 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:

📦 Method 2: Via npm Package

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

🔧 Method 3: Local Installation

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

1. Clone the repository:
   git clone https://github.com/grahama1970/claude-code-mcp-enhanced.git cd claude-code-mcp-enhanced
2. Install dependencies and build:
   npm install npm run build
3. Configure your .mcp.json file to use the local server:

🔑 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.

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:

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 MCP_USE_ROOMODES=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:

Example Response:

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:

Example Usage Scenarios

1. Basic Code Operation

Example MCP Request:

2. Task Orchestration (Boomerang Pattern)

Parent Task Request:

Subtask Request (Generated by Parent):

3. Specialized Mode Request

Example Using Roo Mode:

🔄 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

Workflow Steps

1. User adds the MCP to their configuration file
2. User prompts Claude: "Use convert_task_markdown 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
4. 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:

Response Format:

Markdown Task File Format

Task markdown files should follow this structure:

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):

2. Convert to MCP tasks:

3. 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!
4. The converter transforms generic instructions into exact commands:
   • "Change directory to project and activate .venv" becomes:
     cd /home/user/project && source .venv/bin/activate
   • All paths are resolved to absolute paths
   • All commands are fully executable with no ambiguity
5. Execute the converted tasks: The returned tasks contain exact, executable commands and can be executed sequentially using the claude_code tool.

Complete Example: From Markdown to Execution

Step 1: User creates a markdown task file (project_tasks.md):

Step 2: User prompts Claude:

Step 3: MCP converts and validates:

• If format is correct: Returns executable JSON
• If format is wrong: Returns error with guidance

Step 4: Result (if successful):

Step 5: Claude can execute each task sequentially

Format Validation and Error Handling

The task converter enforces a specific markdown structure to ensure consistent and reliable task conversion. If your markdown file is incorrectly formatted, the converter provides helpful error messages:

Example error response:

The validation ensures:

1. Required sections are present (Title, Objective, Requirements)
2. Tasks use proper checkbox format
3. Each task has indented steps
4. Requirements use checkbox format for consistency

🦚 Task Orchestration Patterns

This MCP server supports powerful task orchestration capabilities to handle complex workflows efficiently.

Boomerang Pattern (Claude Desktop ⟷ Claude Code)

The Boomerang pattern allows Claude Desktop to orchestrate tasks and delegate them to Claude Code. This allows you to:

1. Break down complex workflows into smaller, manageable subtasks
2. Pass context from parent tasks to subtasks
3. Get results back from subtasks to the parent task
4. Choose between detailed or summarized results
5. Track and manage progress through structured task lists

Boomerang Pattern Visualization

Here's a simple diagram showing how Claude breaks down a recipe task into steps and delegates them to Claude Code:

In this example:

1. The user asks Claude to make a chocolate cake recipe
2. Claude (Parent) breaks this down into separate tasks
3. Claude delegates "Find recipe" task to Claude Code with a parent task ID
4. Claude Code returns the recipe information to Claude
5. Claude delegates "Convert measurements" task to Claude Code
6. Claude Code returns the converted measurements
7. Claude combines all results and presents the complete solution to the user

Simple Task Examples:

Task 1 - Find Recipe:

Task 2 - Convert Measurements:

How It Works

1. Creating a Subtask:
   • Generate a unique task ID in your parent task
   • Send a request to the claude_code tool with:
     • Your specific prompt
     • The parent task ID
     • A task description
     • The desired return mode ('summary' or 'full')
2. Receiving Results:
   • The subtask result will include a special marker: <!-- BOOMERANG_RESULT {...} -->
   • This marker contains JSON with the task metadata
   • The parent task can parse this to identify completed subtasks
3. Example Workflow with Claude Desktop:

This approach is particularly useful for complex tasks that require deep analysis or multiple steps.

Comprehensive Task List Management Example

Here's a detailed example of using Claude with the Claude Code MCP to manage and execute a structured task list:

1. Setting Up Task List Structure

First, create a task list file (e.g., tasks.md) with the following structure:

2. Executing the Task List

Claude can now systematically work through the tasks using Claude Code:

3. Continuing with Subsequent Tasks

After getting confirmation, Claude would continue with the next subtask:

This structured approach enables Claude to systematically work through complex task lists while maintaining clear documentation of progress, assumptions, and relevant files throughout the process.

🎭 Self-Orchestration Pattern (Claude Code as Orchestrator)

While Claude Desktop is often used as the parent agent, you can use Claude Code itself as both the orchestrator and executor. This approach creates a self-contained system where Claude Code manages its own task orchestration, without requiring Claude Desktop.

Implementation Steps

1. Create an entry script that initializes your task structure and launches Claude Code as the orchestrator
2. Design a task data structure (typically in JSON format) that tracks task status and dependencies
3. Create task executor scripts to process individual tasks and update task state

Key Benefits of Self-Orchestration

1. Self-contained: No external orchestrator (like Claude Desktop) required
2. Persistent state: All task information is stored in JSON files
3. Error recovery: Can resume from the last successful task if interrupted
4. Simplified dependency management: Single system manages all Claude Code interactions
5. Shell script automation: Easily integrated into CI/CD pipelines or automated workflows

For a detailed implementation guide with example scripts and task structures, see Self-Orchestration with Claude Code.

👓 Roo Modes Integration

This MCP server supports integration with specialized modes through a .roomodes configuration file. When enabled, you can specify which mode to use for each task, allowing for specialized behavior.

How to Use Roo Modes

1. Enable Roo Mode Support:
   • Set the environment variable MCP_USE_ROOMODES=true in your MCP configuration
   • Create a .roomodes file in the root directory of your MCP server
   • Optionally enable hot-reloading with MCP_WATCH_ROOMODES=true to automatically reload the configuration when the file changes
2. Configure Your Modes:
   • The .roomodes file should contain a JSON object with a customModes array
   • Each mode should have a slug, name, roleDefinition, and optionally an apiConfiguration with a modelId
3. Using a Mode:
   • When making requests to the claude_code tool, include a mode parameter with the slug of the desired mode
   • The MCP server will automatically apply the role definition and model configuration
4. Example .roomodes File:
   { "customModes": [ { "slug": "coder", "name": "💻 Coder", "roleDefinition": "You are a coding specialist who writes clean, efficient code.", "apiConfiguration": { "modelId": "claude-3-sonnet-20240229" } }, { "slug": "designer", "name": "🎨 Designer", "roleDefinition": "You are a design specialist focused on UI/UX solutions." } ] }
5. Environment Configuration Example:
   { "mcpServers": { "claude-code-mcp-enhanced": { "command": "npx", "args": ["github:grahama1970/claude-code-mcp-enhanced"], "env": { "MCP_USE_ROOMODES": "true", "MCP_WATCH_ROOMODES": "true", "MCP_CLAUDE_DEBUG": "false" } } } }
6. Making Requests with Modes:
   { "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" } }

Key Features of Roo Modes:

• Specialized Behaviors: Different modes can have different system prompts and model configurations
• Hot Reloading: When MCP_WATCH_ROOMODES=true, the server automatically reloads the configuration when the .roomodes file changes
• Performance: The server caches the roomodes configuration for better performance
• Fallback: If a mode isn't found or roomodes are disabled, the server continues with default behavior

🛠️ Enhanced Reliability Features

This server includes several improvements to enhance reliability and performance:

1. Heartbeat & Timeout Prevention

To prevent client-side timeouts during long-running operations:

• Added a configurable heartbeat mechanism that sends progress updates every 15 seconds
• Implemented execution time tracking and reporting
• Added configurable timeout parameters through environment variables

2. Robust Error Handling with Retries

Added intelligent retry logic for transient errors:

• Implemented automatic retry with configurable parameters
• Added error classification to identify retryable issues
• Created detailed error reporting and tracking

3. Request Tracking System

Implemented comprehensive request lifecycle management:

• Added unique IDs for each request
• Created tracking for in-progress requests
• Ensured proper cleanup on completion or failure

4. Graceful Shutdown

Added proper process termination handling:

• Implemented signal handlers for SIGINT and SIGTERM
• Added tracking for in-progress requests
• Created wait logic for clean shutdown
• Ensured proper cleanup on exit

5. Configuration Caching and Hot Reloading

Added performance optimization for configuration:

• Implemented caching for roomodes file
• Added automatic invalidation based on file changes
• Created configurable file watching mechanism

⚙️ Configuration Options

The server's behavior can be customized using these environment variables:

These can be set in your shell environment or within the env block of your mcp.json server configuration.

📸 Visual Examples

Here are some visual examples of the server in action:

Fixing ESLint Setup

Here's an example of using the Claude Code MCP tool to interactively fix an ESLint setup by deleting old configuration files and creating a new one:

Listing Files Example

Here's an example of the Claude Code tool listing files in a directory:

Complex Multi-Step Operations

This example illustrates claude_code handling a more complex, multi-step task, such as preparing a release by creating a branch, updating multiple files (package.json, CHANGELOG.md), committing changes, and initiating a pull request, all within a single, coherent operation.

GitHub Actions Workflow Correction

🎯 Key Use Cases

This server, through its unified claude_code tool, unlocks a wide range of powerful capabilities by giving your AI direct access to the Claude Code CLI. Here are some examples of what you can achieve:

1. Code Generation, Analysis & Refactoring:
   • "Generate a Python script to parse CSV data and output JSON."
   • "Analyze my_script.py for potential bugs and suggest improvements."
2. File System Operations (Create, Read, Edit, Manage):
   • Creating Files: "Your work folder is /Users/steipete/my_project\n\nCreate a new file named 'config.yml' in the 'app/settings' directory with the following content:\nport: 8080\ndatabase: main_db"
   • Editing Files: "Your work folder is /Users/steipete/my_project\n\nEdit file 'public/css/style.css': Add a new CSS rule at the end to make all 'h2' elements have a 'color: navy'."
   • Moving/Copying/Deleting: "Your work folder is /Users/steipete/my_project\n\nMove the file 'report.docx' from the 'drafts' folder to the 'final_reports' folder and rename it to 'Q1_Report_Final.docx'."
3. Version Control (Git):
   • "Your work folder is /Users/steipete/my_project\n\n1. Stage the file 'src/main.java'.\n2. Commit the changes with the message 'feat: Implement user authentication'.\n3. Push the commit to the 'develop' branch on origin."
4. Running Terminal Commands:
   • "Your work folder is /Users/steipete/my_project/frontend\n\nRun the command 'npm run build'."
   • "Open the URL https://developer.mozilla.org in my default web browser."
5. Web Search & Summarization:
   • "Search the web for 'benefits of server-side rendering' and provide a concise summary."
6. Complex Multi-Step Workflows:
   • Automate version bumps, update changelogs, and tag releases: "Your work folder is /Users/steipete/my_project\n\nFollow these steps: 1. Update the version in package.json to 2.5.0. 2. Add a new section to CHANGELOG.md for version 2.5.0 with the heading '### Added' and list 'New feature X'. 3. Stage package.json and CHANGELOG.md. 4. Commit with message 'release: version 2.5.0'. 5. Push the commit. 6. Create and push a git tag v2.5.0."
7. Repairing Files with Syntax Errors:
   • "Your work folder is /path/to/project\n\nThe file 'src/utils/parser.js' has syntax errors after a recent complex edit that broke its structure. Please analyze it, identify the syntax errors, and correct the file to make it valid JavaScript again, ensuring the original logic is preserved as much as possible."
8. Interacting with GitHub (e.g., Creating a Pull Request):
   • "Your work folder is /Users/steipete/my_project\n\nCreate a GitHub Pull Request in the repository 'owner/repo' from the 'feature-branch' to the 'main' branch. Title: 'feat: Implement new login flow'. Body: 'This PR adds a new and improved login experience for users.'"
9. Interacting with GitHub (e.g., Checking PR CI Status):
   • "Your work folder is /Users/steipete/my_project\n\nCheck the status of CI checks for Pull Request #42 in the GitHub repository 'owner/repo'. Report if they have passed, failed, or are still running."

CRITICAL: Remember to provide Current Working Directory (CWD) context in your prompts for file system or git operations (e.g., "Your work folder is /path/to/project\n\n...your command...").

🔧 Troubleshooting

• "Command not found" (claude-code-mcp): If installed globally, ensure the npm global bin directory is in your system's PATH. If using npx, ensure npx itself is working.
• "Command not found" (claude or ~/.claude/local/claude): Ensure the Claude CLI is installed correctly. Run claude/doctor or check its documentation.
• Permissions Issues: Make sure you've run the "Important First-Time Setup" step.
• JSON Errors from Server: If MCP_CLAUDE_DEBUG is true, error messages or logs might interfere with MCP's JSON parsing. Set to false for normal operation.
• ESM/Import Errors: Ensure you are using Node.js v20 or later.
• Client Timeouts: For long-running operations, the server sends heartbeat messages every 15 seconds to prevent client timeouts. If you still experience timeouts, you can adjust the heartbeat interval using the MCP_HEARTBEAT_INTERVAL_MS environment variable.
• Network/Server Errors: The server now includes automatic retry logic for transient errors. If you're still experiencing issues, try increasing the MCP_MAX_RETRIES and MCP_RETRY_DELAY_MS values.
• Claude CLI Fallback Warning: If you see a warning about Claude CLI not found at ~/.claude/local/claude, this is normal. The server is falling back to using the claude command from your PATH. You can set the CLAUDE_CLI_PATH environment variable to specify the exact path to your Claude CLI executable if needed.

👨‍💻 For Developers: Local Setup & Contribution

If you want to develop or contribute to this server, or run it from a cloned repository for testing, please see our Local Installation & Development Setup Guide.

💪 Contributing

Contributions are welcome! Please refer to the Local Installation & Development Setup Guide for details on setting up your environment.

Submit issues and pull requests to the GitHub repository.

⚖️ License

MIT

💬 Feedback and Support

If you encounter any issues or have questions about using the Claude Code MCP server, please:

1. Check the Troubleshooting section above
2. Submit an issue on the GitHub repository
3. Join the discussion in the repository discussions section

We appreciate your feedback and contributions to making this tool better!