ai-cli-mcp — Claude Code MCP server: run AI CLIs in the background
An MCP server that lets your agent fire off Claude, Claude, Gemini or OpenCode CLI jobs in the background and keep working while they run.
claude mcp add ai-cli-mcp -- npx -y ai-cli-mcpWhat ai-cli-mcp does
The server exposes a single run tool. Your agent in Claude, Cursor or Claude hands it a task and a model name; the outside CLI executes it as a separate process with PID tracking. Control comes back right away, so the calling model can start the next job or spin up another agent. wait blocks until the work finishes and returns a parsed result, and the response carries a session_id you pass to later runs so a large codebase isn't read twice.
Models are picked by name: Claude (sonnet, opus, haiku), Claude (gpt-5.3-codex, gpt-5.5), Gemini, Claude, OpenCode and Pi. Gemini runs through the Antigravity CLI agy; GROK_CLI_NAME and PI_CLI_NAME override the binary name or path for those two. Each CLI has to be installed and signed in locally, so an unconfigured opencode means that run fails. For Claude you need a passing claude doctor plus one manual launch where you accept --dangerously-skip-permissions.
Permits come from bypassing confirmations: Claude runs with --dangerously-skip-permissions, Claude with --dangerously-bypass-approvals-and-sandbox. The agent edits files and executes commands in your working folder without asking. Keep that on a git-tracked repo rather than a directory holding anything you can't restore.
What it helps with
- run several agents in parallel on different models
- collect the output of a background job when it finishes
- resume a session by
session_idinstead of resending context - call an outside AI CLI from Cursor or Claude
- split a refactor and its unit tests across two models
Example prompts for the agent
- Run the
src/backendrefactor throughrunonsonnet, thenwaitand show me the result - Read every file under
src/withrunonopus, give me thesession_id, then start two jobs ongpt-5.3-codexwith it - Start a project review via
runwithgemini-3.1-pro-highand--cwd ./project
How to install ai-cli-mcp
Platform CLI
claude mcp add ai-cli-mcp -- npx -y ai-cli-mcpPlatform CLI
codex mcp add ai-cli-mcp -- npx -y ai-cli-mcpConfig file
{
"mcpServers": {
"ai-cli-mcp": {
"command": "npx",
"args": [
"-y",
"ai-cli-mcp"
]
}
}
}Config file
{
"servers": {
"ai-cli-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"ai-cli-mcp"
]
}
}
}Platform CLI
gemini mcp add ai-cli-mcp npx -y ai-cli-mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about ai-cli-mcp
How do I install ai-cli-mcp in Claude Code?
Run claude mcp add ai-cli-mcp -- npx -y ai-cli-mcp. Restart the session afterwards so the server comes up.
What does ai-cli-mcp do?
It launches an outside AI CLI (Claude, Claude, Gemini, OpenCode, Claude, Pi) as a background process when your agent asks, tracks the PID, and hands back a structured answer.
What has to be set up first?
Whichever CLIs you plan to call must be installed and authenticated locally. For Claude a clean claude doctor and one manual run accepting --dangerously-skip-permissions are enough; the other CLIs are optional.
