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.

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

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 installed and authenticated

Configuration

Add to your ~/.mcp.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

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

Permission Handling

When Claude Code needs permission, you'll receive:

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

{
  "tool": "respond",
  "params": {
    "sessionId": "abc-123",
    "action": "approve"
  }
}

Deny:

{
  "tool": "respond",
  "params": {
    "sessionId": "abc-123",
    "action": "deny"
  }
}

Redirect (provide alternative instructions):

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

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