AI CLI MCP Server
📦 Package Migration Notice: This package was formerly and has been renamed to to reflect its expanded support for multiple AI CLI tools.
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y [email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add ai-cli-mcp -- npx -y ai-cli-mcp@3.1.0在終端機中執行。
{ "mcpServers": { "ai-cli-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令？ 兩種安裝方式的差異
來自發布者
📦 Package Migration Notice: This package was formerly and has been renamed to to reflect its expanded support for multiple AI CLI tools.
Run Claude, Codex, Antigravity, OpenCode, Grok, and Pi CLIs through MCP with background jobs
@mkxultra/claude-code-mcpai-cli-mcpAn 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.
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:
--dangerously-skip-permissions)--dangerously-bypass-approvals-and-sandbox)agy --print, stream-json, and --dangerously-skip-permissions)streaming-messages-json, automatic tool approval, and automatic updates disabledopencode run --format json --dir <workFolder> <prompt>)grok, grok-4.6, grok-4.5), OpenCode (opencode plus oc-<provider/model>), and Pi (pi plus pi-<provider/model>)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:
- Refactor
src/backendcode usingsonnet- Create unit tests for
src/frontendusinggpt-5.3-codex- Update docs in
docs/usinggemini-3.1-pro-highWhile they run, please update the TODO list. Once done, use the
waittool to wait for all completions and report the results together.
You can reuse heavy context (like large codebases) using session IDs to save costs while running multiple tasks.
- First, use
acm mcp runwithopusto read all files insrc/and understand the project structure.- Use the
waittool to wait for completion and retrieve thesession_idfrom the result.- Using that
session_id, run the following two tasks in parallel withacm mcp run:
- Create refactoring proposals for
src/utilsusingsonnet- Add architecture documentation to
README.mdusinggpt-5.3-codex- Finally,
waitagain to combine both results.
The only prerequisite is that the AI CLI tools you want to use are locally installed and correctly configured.
claude doctor passes, and execution with --dangerously-skip-permissions is approved (you must run it manually once to login and accept terms).agy and sign in once; tested with 1.2.5. See the migration instructions below.~/.grok/bin/grok, then PATH; GROK_CLI_NAME overrides either with a command name or absolute path.opencode run --format json, and explicit provider/model selection follows the oc-<provider/model> wrapper syntax exposed by ai-cli models.pi --list-models to see the provider/model pairs available to your account. PI_CLI_NAME overrides the binary name or path.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 entrypointai-cli: human-facing CLI for background AI runsnpxThe recommended way to use the MCP server is via npx.
"ai-cli-mcp": {
"command": "npx",
"args": [
"-y",
"ai-cli-mcp@latest"
]
},
claude mcp add ai-cli '{"name":"ai-cli","command":"npx","args":["-y","ai-cli-mcp@latest"]}'
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-cliai-cli-mcpExamples:
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
npxBecause 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"
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.
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, ensure you're logged in and have accepted any necessary terms:
codex login
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.
ai-cli currently supports:
runpsresultpeekwaitkillcleanupdoctormodelsalias list / alias add / alias rmmcpExample 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 modeloc-<provider/model> for an explicit OpenCode provider/model, for example oc-openai/gpt-5.4ai-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 accept low, medium, high, xhigh, and max reasoning; both Sol models also accept ultra through Codex CLI. Omitting effort uses the CLI default. For example: ai-cli run --cwd "$PWD" --model gpt-6.1-sol --reasoning-effort ultra --prompt "Review this project".
doctor checks only binary availability and path resolution. Its JSON output includes a checks block that marks login state and terms acceptance as unchecked.
Install Pi and sign in once before starting ai-cli or the MCP server. This integration was verified with Pi 0.86.1.
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi # use /login if authentication is not configured
pi --list-models
Use pi to let Pi select its configured default model. Use pi-<provider/model> for an explicit model, for example pi-openai-codex/gpt-6-astra. ai-cli models runs pi --list-models and includes these names after pi in its pi array. dynamicModelBackends.pi.discovery reports discovery status; reasoningEfforts.pi lists off, minimal, low, medium, high, xhigh, and max. Omitting reasoning_effort leaves the choice to Pi.
ai-cli run --cwd "$PWD" --model pi --prompt "Explain this project"
ai-cli run --cwd "$PWD" --model pi-openai-codex/gpt-6-astra --reasoning-effort xhigh --prompt "Review this change"
ai-cli alias add pi-coding pi-openai-codex/gpt-5.6-terra --effort high
ai-cli run --cwd "$PWD" --model pi-coding --session-id <session_id> --prompt "Continue"
Runs use pi --mode json --approve, optional --model, --thinking, and --session, followed by -p -- <prompt>. The --approve flag lets Pi load project resources and execute its configured tools without an interactive confirmation. The existing workFolder and process isolation rules still apply.
peek accumulates Pi text_delta events and optionally reports normalized tool_execution_start / tool_execution_end events. Thinking deltas, tool updates, and raw tool output are excluded. get_result and wait return the final text, provider, model, usage, stop reason, and Pi session ID. Passing that ID to the next run resumes the same session with --session. Verbose results include detailed tool history; compact results omit it. Failed runs preserve diagnostic stderr, and cancellation uses the same process-tree termination used for Grok and Antigravity.
See the Grok headless guide for authentication and CLI setup.
With no user alias named grok, both MCP and ai-cli route grok and native grok-* names to Grok. grok omits --model, using the Grok CLI configuration; explicit names select that model. models includes grok: ["grok", "grok-4.6", "grok-4.5"] and reasoningEfforts.grok with the accepted levels. Other native names are forwarded, with common low/medium/high effort validation; model availability is determined by Grok.
ai-cli run --cwd "$PWD" --model grok --prompt "Explain this project"
ai-cli run --cwd "$PWD" --model grok-4.6 --reasoning-effort xhigh --prompt "Review this change"
ai-cli alias add grok-coding grok-4.6 --effort high
ai-cli run --cwd "$PWD" --model grok-coding --session-id <session_id> --prompt "Continue"
A preexisting user alias named grok keeps precedence, including aliases that target OpenCode. It remains visible in models and alias list and does not affect unrelated runs or MCP tool discovery. Explicit grok-4.6 / grok-4.5 always select the native backend. To use the CLI-configured provider default, rename that alias or explicitly remove it with ai-cli alias rm grok; upgrades never edit your configuration.
The same alias and model, reasoning_effort, and session_id fields work in MCP run. Aliases use the existing user configuration. With no effort supplied, Grok decides the effort. The provider key grok accepts low/medium/high; select grok-4.6 explicitly for xhigh. grok-4.5 accepts low/medium/high. Neither accepts max or ultra.
Commands use grok --single=<prompt> --cwd <workFolder> --output-format streaming-messages-json --always-approve --no-auto-update, plus optional model, effort, and --resume=<session_id>. Attached values preserve leading hyphens and newlines. At the ai-cli surface use --prompt="--text" / --session-id="--id" for values starting with --, or use a prompt file. This follows the existing unattended tool approval policy. Authenticate with Grok before use; doctor.grok checks binary discovery only. The Grok 1.0.13 models command can show an unauthenticated banner even when OAuth headless execution works, so that banner is not used as an authentication test.
peek observes whole assistant messages during the call, plus optional normalized tool start/completion events. Thinking, token deltas, and raw tool output are excluded. get_result and wait return the final answer and session ID, or available assistant text while running. When present, Grok model/usage/cost metadata and terminal is_error, subtype, errors, and stop_reason are retained. Failures also preserve diagnostic stderr, including after a partial answer. Verbose results include detailed tools. kill/kill_process terminate the tracked process and its tool descendants; POSIX cancellation uses ps and signals, and Windows uses taskkill /t /f. If ps is unavailable, it still signals the tracked PID and its owned group, verifies exit and escalates to SIGKILL if needed; the kill response and failure stderr warn that descendants in other groups may survive. The MCP host stops tracked work on SIGINT/SIGTERM/SIGHUP and stdin/transport closure. Group signals target only groups created for tracked work, never the MCP host group.
During MCP cancellation, the Grok root may report failed/143 while its tool descendants are still stopping. Overlapping kill_process calls and host shutdown await the same tree termination; cleanup_processes retains the entry until that operation settles. If the first signal fails before any signal is delivered, the error is returned and later natural completion keeps its actual status and exit code.
Save a model and its default reasoning effort under a name you can use across projects. CLI and MCP share the same user configuration.
The built-in aliases sol and luna select gpt-6.1-sol and gpt-6-luna. They do not set a reasoning effort: omit --reasoning-effort to use the Codex CLI default, or specify it for a run. For example, ai-cli run --cwd "$PWD" --model sol --prompt "Review this project". User aliases with the same names override these defaults; removing the user override with ai-cli alias rm sol restores the built-in target.
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
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.
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.codex-ultra. Each entry replaces the entire definition; omitting reasoning_effort uses the target CLI's default rather than inheriting the built-in effort.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, except that a user alias named grok retains precedence for compatibility.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.
Background CLI runs are stored under:
~/.local/state/ai-cli/cwds/<normalized-cwd>/<pid>/
Each PID directory contains:
meta.jsonstdout.logstderr.logexit-status.json for detached runsUse ai-cli cleanup to remove completed and failed runs. Running processes are preserved.
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.
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.
This server exposes the following tools:
runExecutes 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.
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:claude-ultra (opus, defaults to max effort and does not select Fable), codex-ultra (gpt-6-astra, defaults to ultra reasoning), gemini-ultrasonnet, 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.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.2gemini-3.8-flash-high, gemini-3.8-flash-medium, gemini-3.8-flash-low, Gemini 3.7/3.6 Flash variants, gemini-3.1-pro-high, gemini-3.1-pro-lowgrok for its configured default, grok-4.6, grok-4.5, and other native grok-* namesopencode for the configured default backend model, plus explicit wrappers like oc-openai/gpt-5.4pi for its configured default model, plus explicit wrappers like pi-openai-codex/gpt-6-astrareasoning_effort (string, optional): Reasoning control for Claude, Codex, Grok, and Pi. Pi maps off|minimal|low|medium|high|xhigh|max to --thinking. Grok uses --reasoning-effort: grok-4.6 supports low/medium/high/xhigh; grok-4.5, the grok configured default, and other native Grok names accept low/medium/high. Omit effort to use the CLI default; max/ultra are rejected for Grok. Claude uses --effort (allowed: "low", "medium", "high", "xhigh", "max"). Codex uses model_reasoning_effort (base levels: "low", "medium", "high", "xhigh"; GPT-6.1 Sol, GPT-6 Astra/Sol, and GPT-5.6 Sol/Terra also support "max" and "ultra", while GPT-6 Luna and GPT-5.6 Luna support "max"). Antigravity accepts --effort low|medium|high, which must match the model name suffix when present. OpenCode does not support reasoning_effort.session_id (string, optional): Optional session ID to resume a previous session. Supported for Claude, Codex, Gemini, OpenCode, Grok, and Pi. Grok resumes via --resume; OpenCode and Pi resume in place via --session and may also be combined with explicit model selection.waitWaits for multiple AI agent processes to complete and returns their combined results. Blocks until all specified PIDs finish or a timeout occurs.
Set timeout to 0 to wait until all specified processes finish without an ai-cli deadline. For example, call MCP wait with { "pids": [12345], "timeout": 0 }, or use ai-cli wait 12345 --timeout 0. MCP client or transport timeouts still apply independently. A finite wait timeout returns an error and leaves the processes running.
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): Non-negative maximum wait time in seconds. Defaults to 180 (3 minutes); 0 disables the wait timeout.verbose (boolean, optional): If true, each result item uses the full result shape. Defaults to false.peekStarts 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.peek_time_sec elapses or all target processes reach a terminal state, whichever comes first.peek calls for the same PID are allowed; each has an independent window and may return overlapping events.agent_message text, Claude and Grok whole assistant text content, OpenCode type: "text" events where part.type is "text", Antigravity step_update events, and Pi text_delta events.tool_call events are normalized for Codex command/MCP calls, Claude/Grok tool use/results, Antigravity tool steps, OpenCode tool use, and Pi tool execution start/end events. Tool summaries are bounded one-line strings derived from tool names and input metadata only. Raw tool and command output is excluded.events: [], truncated: false, and error: null.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, opencode, grok, pi, 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_processesLists all running and completed AI agent processes with their status, PID, and basic info.
doctorChecks 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.
modelsLists 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.
The two discovery commands run concurrently with a 5-second timeout and a 1 MiB output limit per CLI. PI_CLI_NAME and OPENCODE_CLI_NAME overrides apply. Discovery uses the calling process's working directory and CLI configuration; listed models are not a guarantee of authentication or model access.
Each dynamicModelBackends.<backend>.discovery contains status (success or error), checkedAt, cached, and an error on failure. A missing CLI, timeout, or parsing error leaves that backend's default key and all other model lists and aliases available. An empty successful list has status: "success" and no additional names.
The MCP server caches discovery results, including failures, for 60 seconds and shares concurrent lookups. Each standalone ai-cli models invocation fetches fresh results. Changes to executable selection, working directory, or environment bypass the cache; changes to CLI config files appear after cache expiry. User aliases are read on every request. Listing MCP tools and starting runs do not trigger discovery.
The aliases array includes built-in defaults merged with user model aliases. Each entry contains name, resolvesTo, agent, and optional defaultReasoningEffort.
get_resultGets 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_processTerminates a running AI agent process by PID.
Arguments:
pid (number, required): The process ID to terminate.npx, ensure npx itself is working.ai-cli): If installed globally, ensure your npm global bin directory is in PATH. If using npx, use npx -y --package ai-cli-mcp@latest ai-cli ....claude/doctor or check its documentation.MCP_CLAUDE_DEBUG is true, error messages or logs might interfere with MCP's JSON parsing. Set to false for normal operation.For development setup, testing, and contribution guidelines, see the Development Guide.
# Deterministic unit, parser, contract, and mocked e2e tests
npm test
# Published npm package contents smoke test
npm run test:package
# Deterministic PR/release gate used by GitHub Actions.
# This does not enable real external CLI runs by itself.
npm run test:release
# Release-time live E2E against real installed AI CLIs
ACM_LIVE_E2E=1 ACM_LIVE_E2E_AGENTS=claude,codex npm run test:live
# Release-time live E2E for both ai-cli and MCP server surfaces
ACM_LIVE_E2E=1 ACM_LIVE_E2E_SURFACE=all ACM_LIVE_E2E_AGENTS=claude,codex npm run test:live
Live E2E is opt-in because it depends on installed and authenticated external CLIs, network access, provider availability, and cost budget. ACM_LIVE_E2E_SURFACE defaults to cli; use mcp or all to include the MCP server surface.
Normally not required, but useful for customizing CLI paths or debugging.
CLAUDE_CLI_NAME: Override the Claude CLI binary name or provide an absolute path (default: claude)CODEX_CLI_NAME: Override the Codex CLI binary name or provide an absolute path (default: codex)ANTIGRAVITY_CLI_NAME: Override the Antigravity binary name or absolute path (default: agy). The deprecated GEMINI_CLI_NAME is a lower-priority override and must also point to an Antigravity binary.ANTIGRAVITY_PRINT_TIMEOUT: Override Antigravity’s run limit with a positive duration such as 1h (integration default: 2h; 0 is not unlimited).GROK_CLI_NAME: Override the Grok CLI binary name or absolute path (default discovery: ~/.grok/bin/grok, then grok on PATH)OPENCODE_CLI_NAME: Override the OpenCode CLI binary name or provide an absolute path (default: opencode)PI_CLI_NAME: Override the Pi CLI binary name or provide an absolute path (default: pi)MCP_CLAUDE_DEBUG: Enable debug logging (set to true for verbose output)CLI Name Specification:
CLAUDE_CLI_NAME=claude-customCLAUDE_CLI_NAME=/path/to/custom/claude
Relative paths are not supported. "ai-cli-mcp": {
"command": "npx",
"args": [
"-y",
"ai-cli-mcp@latest"
],
"env": {
"CLAUDE_CLI_NAME": "claude-custom",
"CODEX_CLI_NAME": "codex-custom",
"OPENCODE_CLI_NAME": "opencode-custom",
"PI_CLI_NAME": "pi-custom"
}
},
MIT
Run Claude, Codex, Antigravity, OpenCode, Grok, and Pi CLIs through MCP with background jobs
{ "mcpServers": { "ai-cli-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式，而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Ai Cli 透過 stdio 在本機執行。
上次檢查時間：2026-10-27。 Run Claude, Codex, Antigravity, OpenCode, Grok, and Pi CLIs through MCP with background jobs