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, Forge, and OpenCode) 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 CLI with automatic approval mode (using -y)
• Execute Forge CLI in non-interactive mode (using forge -C <workFolder> -p <prompt>)
• Execute OpenCode in non-interactive JSON mode (using opencode run --format json --dir <workFolder> <prompt>)
• Support multiple AI models: Claude (sonnet, sonnet[1m], opus, opusplan, fable, haiku), Codex (gpt-6-astra, 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-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview), Forge (forge), and OpenCode (opencode plus explicit oc-<provider/model> wrappers such as oc-openai/gpt-5.4)
• 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-2.5-pro

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, and Forge 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.
• Gemini CLI (Optional): Installed and initial setup (login etc.) completed.
• Forge CLI (Optional): Installed and initial setup completed.
• OpenCode (Optional): Installed and configured. This integration uses opencode run --format json, and explicit provider/model selection follows the oc-<provider/model> wrapper syntax exposed by ai-cli models.

Installation & Usage

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

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 Gemini CLI:

For Gemini, ensure you're logged in and have configured your credentials:

gemini auth login

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 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-<provider/model> for an explicit OpenCode provider/model, for example oc-openai/gpt-5.4

ai-cli models exposes OpenCode machine-readably via opencode: ["opencode"] plus dynamicModelBackends.opencode, which points users to opencode models for backend-native discovery.

Codex model selection uses gpt-5.4 as the default advertised model.

doctor checks only binary availability and path resolution. Its JSON output includes a checks block that marks login state and terms acceptance as unchecked.

User Model Aliases

Save a model and its default reasoning effort under a name you can use across projects. CLI and MCP share the same user configuration.

Manage and use aliases from the CLI

ai-cli alias add codex-coding gpt-5.6-terra --effort xhigh
ai-cli alias add claude-review opus --effort max
ai-cli alias list
ai-cli run --cwd "$PWD" --model codex-coding --prompt "fix failing tests"

Here, codex-coding runs gpt-5.6-terra with xhigh reasoning. Override the effort for a single run with --reasoning-effort low.

alias list prints JSON with configPath and an aliases array containing the effective built-in and user aliases. Each entry has name, resolvesTo, agent, and optional defaultReasoningEffort, matching the aliases in ai-cli models. Listing does not create or modify the config file. Use ai-cli models to include the supported model catalog as well.

alias add <name> <model> [--effort <level>] creates the config file and its parent directories if needed, including an explicitly selected AI_CLI_CONFIG_PATH. Reusing a name replaces its definition; omitting --effort clears any previous alias effort. --reasoning-effort and --reasoning_effort are also accepted. Invalid definitions leave the file unchanged.

# Update the default effort
ai-cli alias add codex-coding gpt-5.6-terra --effort high
# Clear the alias effort and use the target CLI's default
ai-cli alias add codex-coding gpt-5.6-terra
# Remove the user alias
ai-cli alias rm codex-coding

alias rm <name> removes only a user definition. Removing an override such as codex-ultra restores the built-in default. Removing an unknown name or a built-in alias without a user override returns an error. Successful commands print JSON with the config path and the change made. Use ai-cli alias --help for usage.

# Override a built-in alias
ai-cli alias add codex-ultra gpt-5.6-terra --effort xhigh
# Restore its built-in gpt-6-astra / ultra definition
ai-cli alias rm codex-ultra

Use aliases through MCP

After registering codex-coding as above, pass its name to the MCP run tool:

{
  "workFolder": "/absolute/path/to/project",
  "model": "codex-coding",
  "prompt": "fix failing tests"
}

Add "reasoning_effort": "low" to override the effort for that request. ai-cli models and the MCP models tool expose the effective aliases as aliases entries with name, resolvesTo, agent, and optional defaultReasoningEffort fields.

Config is read for each run, models, and MCP tool-list request. Changes apply to subsequent requests without restarting the MCP server, provided CLI and MCP use the same config path.

Configuration file and rules

The commands above edit ~/.config/ai-cli/config.json. You can also edit it directly; for example, this file defines both aliases from the first example:

{
  "model_aliases": {
    "codex-coding": {
      "model": "gpt-5.6-terra",
      "reasoning_effort": "xhigh"
    },
    "claude-review": {
      "model": "opus",
      "reasoning_effort": "max"
    }
  }
}

• model is required; reasoning_effort is optional. The backend is selected from the target model, regardless of the alias name.
• Effort precedence is: explicit run argument → alias default → target CLI default. Effort must be supported by the target model; Gemini, Forge, and OpenCode aliases must omit it.
• User entries can override built-in aliases such as codex-ultra. Each entry replaces the entire definition; omitting reasoning_effort uses the target CLI's default rather than inheriting the built-in effort.
• Targets must be native model names such as gpt-5.6-terra, opus, or oc-openai/gpt-5.4; alias chaining is not supported. Alias names are case-sensitive, start with an ASCII letter, and contain only ASCII letters, digits, _, or -. Listed native model names, codex, and the oc- prefix are reserved.
• Missing default config files preserve built-in behavior. Malformed files and invalid model/effort combinations produce errors with the config path. A missing explicitly configured file also produces an error, except that alias add can create it.

An absolute XDG_CONFIG_HOME changes the default location to $XDG_CONFIG_HOME/ai-cli/config.json. AI_CLI_CONFIG_PATH overrides that location entirely; relative paths are resolved from the CLI/MCP process's working directory. For an MCP-specific path, set AI_CLI_CONFIG_PATH in the server's env settings. There is no project-level config lookup. The file uses JSON without comments and currently supports only model_aliases.

CLI State Storage

Background CLI runs are stored under:

~/.local/state/ai-cli/cwds/<normalized-cwd>/<pid>/

Each PID directory contains:

• meta.json
• stdout.log
• stderr.log
• exit-status.json for detached runs

Use ai-cli cleanup to remove completed and failed runs. Running processes are preserved.

Exit Status Tracking

Detached ai-cli runs persist natural exit status for all supported backends through exit-status.json. Non-zero exits are surfaced as failed with the recorded exitCode; zero exits are surfaced as completed with exitCode: 0. ai-cli kill records SIGTERM termination as a failed exit, and a tracked process that disappears without exit metadata is treated as failed rather than assumed successful.

Connecting to Your MCP Client

After setting up the server, add the configuration to your MCP client's settings file (e.g., mcp.json for Cursor, mcp_config.json for Windsurf).

If the file doesn't exist, create it and add the ai-cli-mcp configuration.

Tools Provided

This server exposes the following tools:

run

Executes a prompt using Claude CLI, Codex CLI, Gemini CLI, Forge CLI, or OpenCode. The appropriate CLI is automatically selected based on the model name.

Arguments:

• prompt (string, optional): The prompt to send to the AI agent. Either prompt or prompt_file is required.
• prompt_file (string, optional): Path to a file containing the prompt. Either prompt or prompt_file is required. Can be absolute path or relative to workFolder.
• workFolder (string, required): The working directory for the CLI execution. Must be an absolute path. Models:
• Ultra Aliases (built-in defaults; user config can override): claude-ultra (opus, defaults to max effort and does not select Fable), codex-ultra (gpt-6-astra, defaults to ultra reasoning), gemini-ultra
• Claude: sonnet, sonnet[1m], opus, opusplan, fable, haiku
  • fable explicitly selects Claude Code's latest Fable model. Fable may require separately billed usage credits and is not selected by the built-in claude-ultra default.
• Codex: gpt-6-astra, 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-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview
• Forge: forge
• OpenCode: opencode for the configured default backend model, plus explicit wrappers like oc-openai/gpt-5.4
• reasoning_effort (string, optional): Reasoning control for Claude and Codex. Claude uses --effort (allowed: "low", "medium", "high", "xhigh", "max"). Codex uses model_reasoning_effort (base levels: "low", "medium", "high", "xhigh"; GPT-6 Astra and GPT-5.6 Sol/Terra also support "max" and "ultra", while GPT-5.6 Luna supports "max"). Gemini, Forge, and OpenCode do not support reasoning_effort.
• session_id (string, optional): Optional session ID to resume a previous session. Supported for Claude, Codex, Gemini, Forge, and OpenCode. OpenCode resumes in place via --session and may also be combined with an explicit oc-<provider/model> selection.

wait

Waits for multiple AI agent processes to complete and returns their combined results. Blocks until all specified PIDs finish or a timeout occurs.

By default, each returned result item uses the compact shape shared with get_result(verbose: false): operational fields such as pid, agent, status, exitCode, model, parsed output such as agentOutput, and top-level session_id when available. Set verbose: true to include full metadata like startTime, workFolder, prompt, and detailed parsed output such as agentOutput.tools.

Arguments:

• pids (array of numbers, required): List of process IDs to wait for (returned by the run tool).
• timeout (number, optional): Maximum wait time in seconds. Defaults to 180 (3 minutes).
• verbose (boolean, optional): If true, each result item uses the full result shape. Defaults to false.

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 not a history API, not gapless streaming, and not shell stdout/stderr tailing. Separate peek calls may miss events emitted between calls; --follow is intentionally not part of v1.

CLI v1:

ai-cli peek 123 --time 10
ai-cli peek 123 456 --time 10
ai-cli peek 123 --time 10 --include-tool-calls

Arguments:

• pids (array of numbers, required): 1..32 process IDs returned by run. Duplicate PIDs are deduplicated server-side, preserving first occurrence order. Unknown or unmanaged PIDs are returned per process as not_found, not as a whole-call failure.
• peek_time_sec (number, optional): Positive integer observation length in seconds. Defaults to 10 and is capped at 60. 0, negative values, and fractional values are invalid.
• include_tool_calls (boolean, optional): When true, each process events array includes normalized tool_call events in addition to message events. Defaults to false.

Observation and filtering:

• peek_started_at and events[].ts are ai-cli-mcp server-side UTC RFC3339 timestamps. peek_started_at is when the observation window starts after validation and listener registration; events[].ts is when ai-cli-mcp observed and accepted the event.
• The window ends when peek_time_sec elapses or all target processes reach a terminal state, whichever comes first.
• Events emitted before the window starts are not returned. Concurrent peek calls for the same PID are allowed; each has an independent window and may return overlapping events.
• Message events are recognized from Codex agent_message text, Claude assistant text content, OpenCode type: "text" events where part.type is "text", Gemini stream-json message events where role is "assistant", and best-effort Forge plain-text lines beginning with Summary: or Completed successfully:.
• When tool calls are included, tool_call events are normalized for Codex command/MCP calls, Claude tool use/results, Gemini tool use/results, OpenCode completed tool use events, and low-precision Forge Execute/Finished markers. Tool summaries are bounded one-line strings derived from tool names and input metadata only. Forge command output itself is not tailed or exposed. Raw stdout/stderr, raw JSONL, tool result output, command output, result.response, stats, token usage, and verbose metadata are excluded.
• Unknown event shapes are denied by default. Managed agents without supported extraction return their real process status with events: [], truncated: false, and error: null.
• Each PID keeps the first 50 events observed in the window. If later events are dropped, truncated is true.
• status is one of running, completed, failed, or not_found, and reflects state when the observation window closes.
• agent is claude, codex, gemini, forge, opencode, a future tracked string value, or null when the process is not found or the agent cannot be determined.

Example response:

{
  "peek_started_at": "2026-04-11T12:34:56.789Z",
  "observed_duration_sec": 10.01,
  "processes": [
    {
      "pid": 123,
      "agent": "codex",
      "status": "running",
      "events": [
        { "kind": "message", "ts": "2026-04-11T12:34:59.120Z", "text": "I'm checking the implementation." },
        { "kind": "tool_call", "ts": "2026-04-11T12:35:00.000Z", "phase": "started", "id": "item_0", "tool": "command_execution", "summary": "/bin/sh -c 'echo hi'" }
      ],
      "truncated": false,
      "error": null
    },
    {
      "pid": 999,
      "agent": null,
      "status": "not_found",
      "events": [],
      "truncated": false,
      "error": "process not found"
    }
  ]
}

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, aliases, and dynamic backend discovery hints from MCP clients. This returns the same structured payload as ai-cli models.

The aliases array includes built-in defaults merged with user model aliases. Each entry contains name, resolvesTo, agent, and optional defaultReasoningEffort.

get_result

Gets the current output and status of an AI agent process by PID.

By default, this returns the compact result shape: operational fields such as pid, agent, status, exitCode, model, parsed output such as agentOutput, and top-level session_id when available. It omits metadata fields like startTime, workFolder, and prompt. Set verbose: true to return the full result shape including those metadata fields and detailed parsed output such as agentOutput.tools. If parsed output is unavailable or incomplete, the raw stdout/stderr fallback is preserved.

Arguments:

• pid (number, required): The process ID returned by the run tool.
• verbose (boolean, optional): If true, returns the full result shape. Defaults to false.

kill_process

Terminates a running AI agent process by PID.

Arguments:

• pid (number, required): The process ID to terminate.

Troubleshooting