# Claude Code Mcp Enhanced

> Enhanced Claude Code MCP server with orchestration capabilities, reliability improvements, and self-contained execution patterns

- **Type:** MCP server
- **Install:** `agentstack add mcp-grahama1970-claude-code-mcp-enhanced`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [grahama1970](https://agentstack.voostack.com/s/grahama1970)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [grahama1970](https://github.com/grahama1970)
- **Source:** https://github.com/grahama1970/claude-code-mcp-enhanced

## Install

```sh
agentstack add mcp-grahama1970-claude-code-mcp-enhanced
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🤖 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](https://github.com/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:

```json
{
  "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:

```json
{
  "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
   ```

2. Install dependencies and build:
   ```bash
   npm install
   npm run build
   ```

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

```json
{
  "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.

```bash
npm install -g @anthropic-ai/claude-code
```
```bash
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:

```json
{
  "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 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:**
```json
{
  "toolName": "claude_code:health",
  "arguments": {}
}
```

**Example Response:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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):**
```json
{
  "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:**
```json
{
  "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

```mermaid
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 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:**
```json
{
  "tool": "convert_task_markdown",
  "arguments": {
    "markdownPath": "/path/to/tasks.md",
    "outputPath": "/path/to/output.json" // optional
  }
}
```

**Response Format:**
```json
{
  "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:

```markdown
# 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`):
```markdown
# 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
```

2. **Convert to MCP tasks**:
```json
{
  "tool": "convert_task_markdown",
  "arguments": {
    "markdownPath": "/project/tasks/api_validation.md"
  }
}
```

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 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](https://github.com/grahama1970)
- **Source:** [grahama1970/claude-code-mcp-enhanced](https://github.com/grahama1970/claude-code-mcp-enhanced)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-grahama1970-claude-code-mcp-enhanced
- Seller: https://agentstack.voostack.com/s/grahama1970
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.