# ai-cli-mcp [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/mkXultra/ai-cli-mcp  
**GitHub Stars:** 27  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ai-cli-mcp

## Description
MCP server for AI CLI tools (Claude, Codex, and Gemini) with background process management

## Tools
Capabilities this server exposes over MCP:

- **run** — Executes a prompt using Claude CLI, Codex CLI, Antigravity CLI (Gemini), OpenCode, Grok, or Pi. The appropriate CLI is automatically selected based on the model name.
- **wait** — Waits for multiple AI agent processes to complete and returns their combined results. Blocks until all specified PIDs finish or a timeout occurs.
- **peek** — Starts a one-shot short observation window for running child agents and returns structured events observed during that specific call. By default this includes only natural-language message events; pass `include_tool_calls` or `--include-tool-calls` to also include normalized tool-call events. It is…
- **list_processes** — Lists all running and completed AI agent processes with their status, PID, and basic info.
- **doctor** — Checks supported AI CLI binary availability and path resolution from MCP clients. Like `ai-cli doctor`, it returns a `checks` block and does not verify login state or terms acceptance.
- **models** — Lists supported model names and aliases, including models discovered by running `pi --list-models` and `opencode models`. This returns the same structured payload as `ai-cli models`. The `pi` and `opencode` arrays retain their default keys and append names ready for `run`.
- **get_result** — Gets the current output and status of an AI agent process by PID.
- **kill_process** — Terminates a running AI agent process by PID.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "ai-cli-mcp": {
    "command": "npx",
    "args": ["-y","--package","ai-cli-mcp@latest","ai-cli"]
  }
}
```

## Documentation

## What ai-cli-mcp does

The ai-cli-mcp MCP server exposes local AI command-line programs through MCP. The requested model determines which CLI is selected.

Runs are tracked by process ID, allowing an MCP client to start several agents and handle other work while they execute. Results can be collected individually or together. This fits repository maintenance, code review, documentation, and other tasks where separate agents can work on distinct areas.

## How it works

The `run` tool accepts a prompt and execution context such as a working directory, model, and, where supported, session information. It returns process information instead of requiring the caller to remain blocked until completion. `wait` accepts multiple process IDs and blocks until they finish or its timeout expires, then combines their results.

Use `peek` for a short observation window over active child agents. It returns structured events from that call, including assistant messages by default and normalized tool-call events when requested. `get_result` reports the current output and status for one PID, while `list_processes` shows active and completed processes with basic status information. `kill_process` terminates a running process.

The ai-cli-mcp MCP server also provides diagnostic and discovery tools. `doctor` checks whether supported CLI binaries can be found from the MCP client environment; it does not check login status or terms acceptance. `models` returns supported model names, aliases, and dynamic backend discovery hints.

## Setup and configuration

The ai-cli-mcp MCP server is distributed as the `ai-cli-mcp` npm package. The documented MCP configuration runs it with `npx -y ai-cli-mcp@latest`. It can also be added through the Claude CLI MCP command. A global npm installation exposes both the human-facing `ai-cli` command and the `ai-cli-mcp` server entrypoint.

Before using a backend, install and configure its local CLI. Claude requires a successful `claude doctor` check and an interactive login and terms-acceptance step. Codex, Antigravity, Grok Build, OpenCode, and Pi are optional backends with their own installation or authentication requirements. Antigravity uses `agy`; its binary path can be overridden with `ANTIGRAVITY_CLI_NAME`. Grok and Pi provide `GROK_CLI_NAME` and `PI_CLI_NAME` overrides. `ANTIGRAVITY_PRINT_TIMEOUT` changes the Antigravity run limit.

## Tools and capabilities

- Launch prompts against several locally installed AI CLIs.
- Run multiple agents asynchronously and track them by PID.
- Wait for groups of processes and combine their results.
- Inspect incremental messages and optional tool-call events.
- Query backend availability, model aliases, and discovery data.
- Resume supported sessions using returned session identifiers.

## Limitations and notes

Execution uses local binaries and their existing account configuration; installing the npm package does not install or authenticate those tools. Some integrations deliberately run with unattended permissions or approval bypasses, including Claude and Codex, so they should be used only in environments where that behavior is acceptable.

Gemini support uses Antigravity CLI rather than the older Gemini CLI output format. The integration has a separate run-time limit from the MCP `wait` timeout, and a zero value for Antigravity means an immediate timeout. Model names and available provider/model pairs can depend on the installed CLI and account configuration.

_Full upstream README: https://allmcps.com/mcp/ai-cli-mcp/readme_