Skip to content
TakoAPI
Back to skills

multi-cli-mcp

by keiranhaax

Aider
โ€”Not yet rated
Your rating

Brief

A unified MCP server that wraps multiple CLI chat tools (qwen, opencode, aider) for Claude Code

Description

# Multi-CLI MCP Server

A unified MCP (Model Context Protocol) server that wraps multiple AI CLI chat tools (qwen, opencode, aider, codex, cursor) with stateful session management and robust process handling.

## Features

- ๐Ÿ”„ **Unified Interface**: Single MCP server for multiple CLI tools
- ๐Ÿ’ฌ **Stateful Sessions**: Maintains conversation context across messages
- ๐Ÿ—๏ธ **Session Isolation**: Each session gets its own workspace
- ๐Ÿ”ง **Process Management**: Health checks, auto-restart, and graceful shutdown
- โšก **Circuit Breaker**: Prevents cascade failures from repeated crashes
- โฑ๏ธ **TTL Cleanup**: Automatic cleanup of idle sessions (30 min default)
- ๐Ÿ›ก๏ธ **Input Sanitization**: Prevents injection attacks
- ๐Ÿ“Š **Structured Logging**: Debug-friendly output

## Installation

```bash
cd /Users/keiranmini/multi-cli-mcp
npm install
npm run build
```

## Configuration

Set environment variables for API keys:

```bash
# For qwen
export QWEN_API_KEY="your-key"
export QWEN_MODEL="qwen3-coder-plus"  # optional

# For opencode
export GROQ_API_KEY="your-key"
export OPENCODE_MODEL="groq/llama-3.3-70b-versatile"  # optional

# For aider
export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"  # optional
export AIDER_MODEL="gpt-4o"  # optional

# For codex
export CODEX_MODEL="gpt-5"  # optional

# For cursor
export CURSOR_API_KEY="your-key"  # or run: cursor-agent login
export CURSOR_MODEL="gpt-5"  # optional
```

## Adding to Claude Code

Add to your Claude Code configuration:

```bash
claude mcp add multi-cli "node /Users/keiranmini/multi-cli-mcp/dist/index.js"
```

Or add directly to your MCP settings file:

```json
{
  "mcpServers": {
    "multi-cli": {
      "command": "node",
      "args": ["/Users/keiranmini/multi-cli-mcp/dist/index.js"],
      "env": {
        "QWEN_API_KEY": "your-key",
        "GROQ_API_KEY": "your-key",
        "OPENAI_API_KEY": "your-key",
        "CURSOR_API_KEY": "your-key"
      }
    }
  }
}
```

## Usage

Once installed, Claude Code will have access to two new tools:

### 1. Chat Tool

Send messages to CLI tools:

```typescript
// Simple message
chat({
  tool: "qwen",
  message: "What is the capital of France?"
})

// With session (maintains context)
chat({
  tool: "opencode",
  message: "Help me write a Python function",
  sessionId: "session_abc123"
})

// With custom model
chat({
  tool: "aider",
  message: "Refactor this code",
  model: "gpt-4o",
  files: ["src/app.py"],
  workingDirectory: "/path/to/project"
})
```

### 2. Session Management

Manage chat sessions:

```typescript
// Create a new session
session({
  action: "create",
  tool: "qwen",
  workingDirectory: "/tmp/my-project"  // optional
})

// List all sessions
session({
  action: "list"
})

// Destroy a session
session({
  action: "destroy",
  sessionId: "session_abc123"
})

// Cleanup idle sessions
session({
  action: "cleanup"
})
```

## Architecture

```
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ Claude Code โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚  Multi-CLI MCP Server โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜     โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                              โ”‚
                    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
                    โ”‚                    โ”‚
            โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”
            โ”‚Session Managerโ”‚    โ”‚Process Managerโ”‚
            โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                    โ”‚                    โ”‚
         โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”        โ”‚
         โ”‚          โ”‚          โ”‚        โ”‚
    โ”Œโ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”   โ”‚
    โ”‚  Qwen  โ”‚ โ”‚OpenCodeโ”‚ โ”‚ Aider โ”‚   โ”‚
    โ”‚Adapter โ”‚ โ”‚Adapter โ”‚ โ”‚Adapterโ”‚   โ”‚
    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜   โ”‚
                                       โ”‚
                            โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
                            โ”‚  CLI Processes      โ”‚
                            โ”‚ (qwen, opencode,    โ”‚
                            โ”‚  aider)             โ”‚
                            โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
```

## Features in Detail

### Session Management
- Each session gets an isolated workspace in `/tmp/multi-cli-mcp/session_*`
- Sessions persist conversation state across messages
- Automatic TTL-based cleanup (30 minutes idle time)
- Maximum 10 concurrent sessions (configurable)

### Process Management
- Health checks every 30 seconds
- Automatic restart on crash (max 3 restarts/minute)
- Circuit breaker prevents cascade failures
- Graceful shutdown with SIGTERM, forced with SIGKILL

### Output Parsing
- Delimiter-based parsing for reliable output extraction
- Buffer management for large outputs
- ANSI escape code removal
- Tool-specific output cleaning

### Error Handling
- Input sanitization to prevent injection
- Timeout handling (30s default, 60s for aider)
- Comprehensive error messages
- Structured logging for debugging

## Development

```bash
# Run in development mode
npm run dev

# Build for production
npm run build

# Start production server
npm start
```

## Troubleshooting

### CLI Tool Not Found
Ensure the CLI tools are installed and accessible:
```bash
which qwen
which opencode
which aider
which codex
which cursor-agent
```

### API Key Issues
Check that environment variables are set:
```bash
echo $QWEN_API_KEY
echo $GROQ_API_KEY
echo $OPENAI_API_KEY
echo $CURSOR_API_KEY
```

### Cursor Authentication
Cursor-agent requires authentication via either:
1. Browser login: `cursor-agent login`
2. API key: Set `CURSOR_API_KEY` environment variable

### Session Issues
- Sessions auto-cleanup after 30 minutes of inactivity
- Maximum 10 concurrent sessions by default
- Check session list with `session({ action: "list" })`

## License

MIT

Installation

Install the skill from https://github.com/keiranhaax/multi-cli-mcp

This skill is not published on the ClawHub registry. Paste the prompt into your coding agent โ€” Claude Code, Cursor, Codex โ€” and it will install the skill straight from the source repository.

Open the repository

Links