AI Cli MCP

AI CLI MCP Server

🇯🇵 日本語のREADMEはこちら

📦 Package Migration Notice: This package was formerly @mkxultra/claude-code-mcp and has been renamed to ai-cli-mcp to reflect its expanded support for multiple AI CLI tools.

An MCP (Model Context Protocol) server that allows running AI CLI tools (Claude, Codex, Gemini, OpenCode, Grok, and Pi) in background processes with automatic permission handling.

Did you notice that Cursor sometimes struggles with complex, multi-step edits or operations? This server, with its powerful unified run tool, enables multiple AI agents to handle your coding tasks more effectively.

Demo

Overview

This MCP server provides tools that can be used by LLMs to interact with AI CLI tools. When integrated with MCP clients, it allows LLMs to:

• Run Claude CLI with all permissions bypassed (using --dangerously-skip-permissions)
• Execute Codex CLI with approvals and sandbox bypassed (using --dangerously-bypass-approvals-and-sandbox)
• Execute Gemini models through Antigravity CLI (agy --print, stream-json, and --dangerously-skip-permissions)
• Execute Grok Build CLI headlessly with streaming-messages-json, automatic tool approval, and automatic updates disabled
• Execute OpenCode in non-interactive JSON mode (using opencode run --format json --dir )
• Execute Pi in non-interactive JSON mode with tool approval enabled for unattended runs
• Support multiple AI models: Claude (sonnet, sonnet[1m], opus, opusplan, fable, haiku), Codex (gpt-6-astra, gpt-6.1-sol, gpt-6-sol, gpt-6-luna, gpt-5.4, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.4-mini, gpt-5.3-codex, gpt-5.3-codex-spark, gpt-5.2), Gemini (gemini-3.8-flash-high/medium/low, gemini-3.7-flash-high/medium/low, gemini-3.6-flash-high/medium/low, gemini-3.1-pro-high/low), Grok (grok, grok-4.6, grok-4.5), OpenCode (opencode plus oc- ), and Pi (pi plus pi- )
• Manage background processes with PID tracking
• Parse and return structured outputs from both tools

Usage Example (Advanced Parallel Processing)

You can instruct your main agent to run multiple tasks in parallel like this:

Launch agents for the following 3 tasks using acm mcp run:

1. Refactor src/backend code using sonnet

2. Create unit tests for src/frontend using gpt-5.3-codex

3. Update docs in docs/ using gemini-3.1-pro-high

While they run, please update the TODO list. Once done, use the wait tool to wait for all completions and report the results together.

Usage Example (Context Caching & Sharing)

You can reuse heavy context (like large codebases) using session IDs to save costs while running multiple tasks.

1. First, use acm mcp run with opus to read all files in src/ and understand the project structure.

2. Use the wait tool to wait for completion and retrieve the session_id from the result.

3. Using that session_id, run the following two tasks in parallel with acm mcp run:

- Create refactoring proposals for src/utils using sonnet

- Add architecture documentation to README.md using gpt-5.3-codex

4. Finally, wait again to combine both results.

Benefits

• True Async Multitasking: Agent execution happens in the background, returning control immediately. The calling AI can proceed with the next task or invoke another agent without waiting for completion.
• CLI in CLI (Agent in Agent): Directly invoke powerful CLI tools like Claude Code or Codex from any MCP-supported IDE or CLI. This enables broader, more complex system operations and automation beyond host environment limitations.
• Freedom from Model/Provider Constraints: Freely select and combine the "strongest" or "most cost-effective" models from Claude, Codex (GPT), Gemini, OpenCode, Grok, and Pi without being tied to a specific ecosystem.

Prerequisites

The only prerequisite is that the AI CLI tools you want to use are locally installed and correctly configured.

• Claude Code: claude doctor passes, and execution with --dangerously-skip-permissions is approved (you must run it manually once to login and accept terms).
• Codex CLI (Optional): Installed and initial setup (login etc.) completed.
• Antigravity CLI (Optional, for Gemini models): Install agy and sign in once; tested with 1.2.5. See the migration instructions below.
• Grok Build CLI (Optional): Install and authenticate Grok locally (tested with 1.0.13 and OAuth). Discovery checks ~/.grok/bin/grok, then PATH; GROK_CLI_NAME overrides either with a command name or absolute path.
• OpenCode (Optional): Installed and configured. This integration uses opencode run --format json, and explicit provider/model selection follows the oc- wrapper syntax exposed by ai-cli models.
• Pi (Optional): Install and authenticate Pi locally (tested with 0.86.1). Run pi --list-models to see the provider/model pairs available to your account. PI_CLI_NAME overrides the binary name or path.

Installation & Usage

Antigravity CLI for Gemini models

The Gemini backend uses Google's Antigravity CLI (agy, tested with 1.2.5). On macOS/Linux:

curl -fsSL https://antigravity.google/cli/install.sh | bash

~/.local/bin/agy # Sign in once interactively agy models ai-cli run --cwd /path/to/project --model gemini-ultra --prompt "Review this project"

On Windows, follow the official PowerShell instructions. Discovery checks ~/.local/bin/agy on macOS/Linux or %LOCALAPPDATA%/agy/bin/agy.exe on Windows, then PATH. Set ANTIGRAVITY_CLI_NAME to override this path.

The backend key remains gemini in doctor, models, and process results. The built-in gemini-ultra selects gemini-3.8-flash-high. Update custom aliases targeting old Gemini CLI names with ai-cli alias add; agy models lists the names available to your account. A supplied reasoning_effort must match the model suffix (for example, gemini-3.8-flash-medium with medium). Other Antigravity model families are not routed through this backend.

peek reads incremental assistant text and optional tool start/completion events. get_result/ai-cli result return the final response and expose Antigravity's conversation_id as session_id; pass it to the next run to resume with --conversation. Old Gemini CLI output parsing and session resumption are not supported.

This integration sets Antigravity's run limit to two hours (2h) by default. Set ANTIGRAVITY_PRINT_TIMEOUT=1h (or another positive duration) in the environment of ai-cli or the MCP server to override it. Antigravity's 0 means an immediate timeout. ACM wait(timeout: 0) only removes the waiting deadline and does not change this separate run limit.

There are now two primary ways to use this package:

• ai-cli-mcp: MCP server entrypoint
• ai-cli: human-facing CLI for background AI runs

MCP usage with npx

The recommended way to use the MCP server is via npx.

Using npx in your MCP configuration:

    "ai-cli-mcp": {

"command": "npx", "args": [ "-y", "ai-cli-mcp@latest" ] },

Using Claude CLI mcp add command:

claude mcp add ai-cli '{"name":"ai-cli","command":"npx","args":["-y","ai-cli-mcp@latest"]}'

Human CLI usage with global install

If you want to use the production CLI directly from your shell, install the package globally:

npm install -g ai-cli-mcp

This exposes both commands:

• ai-cli
• ai-cli-mcp

Examples:

ai-cli doctor

ai-cli models ai-cli run --cwd "$PWD" --model sonnet --prompt "summarize this repository" ai-cli run --cwd "$PWD" --model opencode --prompt "summarize this repository with OpenCode defaults" ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --session-id ses_123 --prompt "continue this session with an explicit OpenCode model" ai-cli run --cwd "$PWD" --model pi-openai-codex/gpt-6-astra --reasoning-effort high --prompt "review this repository with Pi" ai-cli ps ai-cli result 12345 ai-cli result 12345 --verbose ai-cli peek 12345 --time 10 ai-cli wait 12345 --timeout 300 ai-cli wait 12345 --timeout 0 ai-cli wait 12345 --verbose ai-cli kill 12345 ai-cli cleanup ai-cli-mcp

Human CLI usage with npx

Because the published package name is still ai-cli-mcp, the shortest npx form for the CLI is:

npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model sonnet --prompt "hello"

npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "hello from OpenCode"

Important First-Time Setup

Forge CLI support has been removed. models and doctor no longer include Forge, and model: "forge" is rejected. In your user configuration, remove aliases targeting forge or change their targets to supported models. FORGE_CLI_NAME is no longer used.

For Claude CLI:

Before the MCP server can use Claude, you must first run the Claude CLI manually once with the `--dangerously-skip-permissions` flag, login and accept the terms.

npm install -g @anthropic-ai/claude-code

claude --dangerously-skip-permissions

Follow the prompts to accept. Once this is done, the MCP server will be able to use the flag non-interactively.

For Codex CLI:

For Codex, ensure you're logged in and have accepted any necessary terms:

codex login

For Antigravity CLI (Gemini):

Start Antigravity once interactively to sign in:

agy

macOS might ask for folder permissions the first time any of these tools run. If the first run fails, subsequent runs should work.

CLI Commands

ai-cli currently supports:

• run
• ps
• result
• peek
• wait
• kill
• cleanup
• doctor
• models
• alias list / alias add / alias rm
• mcp

Example flow:

ai-cli doctor

ai-cli models ai-cli run --cwd "$PWD" --model gpt-5.4 --prompt "use the default Codex model" ai-cli run --cwd "$PWD" --model codex-ultra --prompt "fix failing tests" ai-cli run --cwd "$PWD" --model opencode --session-id ses_existing --prompt "continue this OpenCode session" ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "run with an explicit OpenCode backend model" ai-cli run --cwd "$PWD" --model pi --prompt "run with Pi's configured default model" ai-cli run --cwd "$PWD" --model pi-openai-codex/gpt-6-astra --reasoning-effort xhigh --prompt "run Pi with an explicit model" ai-cli ps ai-cli peek 12345 --time 10 ai-cli peek 12345 12346 --time 10 ai-cli wait 12345 ai-cli wait 12345 --verbose ai-cli result 12345 ai-cli result 12345 --verbose ai-cli cleanup

run accepts --cwd as the primary working-directory flag and also accepts the older aliases --workFolder / --work-folder for compatibility.

OpenCode model selection accepts either:

• opencode for the CLI's configured default model
• oc- for an explicit OpenCode provider/model, for example oc-openai/gpt-5.4

ai-cli models runs opencode models and returns opencode plus discovered names such as oc-openai/gpt-6-astra in the opencode array. Each name can be passed directly to run. Discovery status and errors are available in dynamicModelBackends.opencode.discovery.

Codex model selection uses gpt-5.4 as the default advertised model. Select gpt-6.1-sol for the latest Sol model, gpt-6-sol for the previous Sol model, or gpt-6-luna for Luna. All three