# Claude Code MCP

An MCP (Model Context Protocol) server that wraps the Claude Code CLI, enabling other AI agents to interact with Claude Code programmatically.

[![npm version](https://badge.fury.io/js/@jawkjiang%2Fclaude-code-mcp.svg)](https://www.npmjs.com/package/@jawkjiang/claude-code-mcp)

## Features

- **Session Management**: Start, continue, and manage multiple conversation sessions
- **Streaming Output**: Real-time output from Claude Code tasks
- **Interrupt Support**: Stop running tasks at any time (like Ctrl+C)
- **Permission Delegation**: When Claude Code needs permission, the outer agent can approve, deny, or redirect
- **Progress Monitoring**: Check task progress and get partial outputs

## Installation

### From npm (Recommended)

```bash
npm install -g @jawkjiang/claude-code-mcp
```

### From source

```bash
git clone https://github.com/jawkjiang/claude-code-mcp.git
cd claude-code-mcp
npm install
npm run build
```

## Prerequisites

- Node.js 18+
- [Claude Code CLI](https://claude.ai/claude-code) installed and authenticated

## Configuration

Add to your `~/.mcp.json`:

### Using npx (Recommended)

```json
{
  "mcpServers": {
    "claude-code": {
      "command": "npx",
      "args": ["@jawkjiang/claude-code-mcp"]
    }
  }
}
```

### Using global install

```json
{
  "mcpServers": {
    "claude-code": {
      "command": "claude-code-mcp"
    }
  }
}
```

### Using local build

```json
{
  "mcpServers": {
    "claude-code": {
      "command": "node",
      "args": ["/path/to/claude-code-mcp/dist/index.js"]
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `chat` | Start a new conversation or continue an existing session |
| `respond` | Respond to permission requests: approve, deny, or redirect with new instructions |
| `interrupt` | Stop a running task (like Ctrl+C) |
| `get_output` | Get current output/progress from a session |
| `list_sessions` | List all active sessions |
| `close_session` | Close and cleanup a session |
| `get_version` | Get Claude Code CLI version |

## Usage Examples

### Basic Chat

```json
{
  "tool": "chat",
  "params": {
    "message": "Create a hello world Python script",
    "workingDirectory": "/path/to/project"
  }
}
```

### Permission Handling

When Claude Code needs permission, you'll receive:

```json
{
  "status": "awaiting_permission",
  "sessionId": "abc-123",
  "pendingPermission": {
    "tool": "Bash",
    "action": "rm -rf /tmp/test",
    "description": "Delete temporary directory"
  },
  "currentOutput": "I need to clean up the temp directory...",
  "message": "Use 'respond' tool to approve, deny, or redirect."
}
```

You can then respond with:

**Approve:**
```json
{
  "tool": "respond",
  "params": {
    "sessionId": "abc-123",
    "action": "approve"
  }
}
```

**Deny:**
```json
{
  "tool": "respond",
  "params": {
    "sessionId": "abc-123",
    "action": "deny"
  }
}
```

**Redirect (provide alternative instructions):**
```json
{
  "tool": "respond",
  "params": {
    "sessionId": "abc-123",
    "action": "redirect",
    "message": "Don't delete the directory. Instead, just remove the .tmp files inside it."
  }
}
```

### Interrupt a Task

```json
{
  "tool": "interrupt",
  "params": {
    "sessionId": "abc-123"
  }
}
```

## Architecture

```
Outer Agent                    claude-code-mcp                Claude Code CLI
    │                              │                              │
    │── chat(message) ────────────>│                              │
    │                              │──── spawn process ──────────>│
    │                              │                              │
    │<── awaiting_permission ─────│<── permission request ───────│
    │                              │                              │
    │── respond(action) ──────────>│                              │
    │   - approve                  │──── send response ──────────>│
    │   - deny                     │                              │
    │   - redirect(new_message)    │                              │
    │                              │                              │
    │<── completed ───────────────│<── task complete ────────────│
```

## Permission Checkpoint Philosophy

Permission requests are not just approve/deny gates - they are **audit and steering points** where the outer agent can:

1. **Review** what Claude Code is doing
2. **Approve** and let it continue
3. **Deny** and stop the current operation
4. **Redirect** with new instructions ("No, do this instead...")

This gives the outer agent the same level of control a human would have when using Claude Code interactively.

## License

MIT

## Author

Created with Claude Code