Claude Code Enhanced MCP server

This MCP (Model Context Protocol) server allows you to run Claude Code in one-shot mode with permissions automatically bypassed. It provides enhanced reliability and task orchestration capabilities for more effective coding tasks.

Installation Options

Via GitHub URL (Recommended)

Add this 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"
      }
    }
  }
}

Via npm Package

{
  "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"
      }
    }
  }
}

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:

   {
     "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"
         }
       }
     }
   }
   

First-Time Setup

Before the MCP server can use the claude_code tool, you must run the Claude CLI manually once:

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

claude --dangerously-skip-permissions

Follow the prompts to accept the terms.

MCP Configuration Locations

Cursor

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

Windsurf

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

Tools Provided

claude_code

Executes a prompt directly using the Claude Code CLI with permissions bypassed.

Arguments:

• prompt (string, required): The prompt to send to Claude Code.
• workFolder (string, optional): The working directory for execution.
• parentTaskId (string, optional): ID of the parent task for orchestration.
• returnMode (string, optional): 'summary' or 'full' (default).
• taskDescription (string, optional): Short description of the task.
• mode (string, optional): Specifies the Roo mode when enabled.

health

Returns health status of the Claude Code MCP server.

convert_task_markdown

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

Example Usage

Basic Code Operation

{
  "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"
  }
}

Task Orchestration

{
  "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"
  }
}

Task Orchestration Patterns

The server supports powerful task orchestration capabilities including:

1. Boomerang Pattern: Claude Desktop breaks down complex workflows into smaller subtasks that are delegated to Claude Code.
2. Self-Orchestration Pattern: Claude Code can act as both orchestrator and executor.

Roo Modes Integration

Enable specialized behaviors through a .roomodes configuration file:

1. Set MCP_USE_ROOMODES=true in your MCP configuration
2. Create a .roomodes file with custom modes
3. Reference the mode in your requests using the mode parameter

Configuration Options

Variable	Description	Default
CLAUDE_CLI_PATH	Path to Claude CLI executable	Auto-detect
MCP_CLAUDE_DEBUG	Enable debug logging	false
MCP_HEARTBEAT_INTERVAL_MS	Progress report interval	15000 (15s)
MCP_EXECUTION_TIMEOUT_MS	CLI execution timeout	1800000 (30m)
MCP_MAX_RETRIES	Max retry attempts	3
MCP_RETRY_DELAY_MS	Delay between retries	1000 (1s)
MCP_USE_ROOMODES	Enable Roo modes	false
MCP_WATCH_ROOMODES	Auto-reload .roomodes	false

Troubleshooting

• "Command not found" (claude-code-mcp): Ensure npm global bin is in PATH
• "Command not found" (claude): Verify Claude CLI installation
• Permissions Issues: Run the "First-Time Setup" step
• JSON Errors: Set MCP_CLAUDE_DEBUG to false
• ESM/Import Errors: Use Node.js v20+
• Client Timeouts: Adjust MCP_HEARTBEAT_INTERVAL_MS
• Network/Server Errors: Increase MCP_MAX_RETRIES and MCP_RETRY_DELAY_MS

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "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"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration 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"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect