Kiro MCP Server

MCP server that lets AI agents with an always-on computer (Grok Bot, Claude, Cursor, Codex, and other MCP clients) orchestrate Kiro CLI V3 coding sessions through typed tools instead of shell commands. It is the Kiro sibling of claude-code-mcp-server.

Requires kiro-cli with the V3 engine, installed and signed in, on the machine that runs this server.

1. Install it: curl -fsSL https://cli.kiro.dev/install | bash (or brew install kiro-cli on macOS).

2. Sign in: run kiro-cli login in a terminal (kiro-cli login --use-device-flow on a machine without a browser).

3. Trust each workspace once: run kiro-cli --v3 in the folder and choose Trust, continue (see Workspace trust).

Without the CLI, tools return CLI_NOT_FOUND with the install command, and the server prints the same warning on stderr at startup. A signed-out CLI gives CLI_NOT_SIGNED_IN. This server never logs in for you.

The server drives Kiro three ways: one long-lived ACP host (kiro-cli acp --agent-engine=v3 --auth-method=cli, newline-delimited JSON-RPC) for sessions, prompts, streaming, permissions, and Kiro's extension methods; headless runs (kiro-cli chat --v3 --no-interactive --output-format stream-json) for fire-and-forget work; and a few fixed-argv subcommands (whoami, settings, agent, mcp, powers). It exposes 32 tools and one subscribable transcript resource. The full feature-parity matrix, with what is exposed, composed, gated, withheld, or impossible and why, is in .kiro/specs/kiro-v3-orchestration/requirements.md.

Design

• Strict schemas, typed results. Every tool has a strict input schema (additionalProperties: false) and an outputSchema, and returns structuredContent. Errors are { "error": { "code", "message", "details" } } with a code from the error table.

• No escape hatch. No shell tool, no raw argv, no field that forwards free-form CLI flags, and no "send any ACP method" tool. Kiro commands that only exist in the terminal UI are mapped to typed tools, or listed as not possible.

• Fixed argv. The only place kiro-cli argv is built is src/argv.ts. Values are attached as --flag=value or follow --; prompts go on stdin. The v2-only --agent, --model, --effort, and --trust-* flags are never passed to acp: agent mode, model, and effort are set through session options.

• Operator policy. Kiro runs only inside KIRO_MCP_ROOTS (checked with realpath). Shell approvals, persistent consent, headless trust flags, and config writes each need an explicit opt-in.

• Bounded processes. Every child is spawned detached in its own process group and tracked. Closing stdin, SIGINT, SIGTERM, or SIGHUP cancels running turns, closes the host's stdin, and stops every process group.

• In memory. Event feeds, jobs, tangent trees, pending permissions, and queued prompts live in memory. The server never writes Kiro's session files. No telemetry; no tokens, KIRO_API_KEY, or authorization URLs in output or logs.

Related MCP server: AKIMCP

Prerequisites

• Node.js 20 or later.

• kiro-cli 2.37 or later with the V3 engine (kiro-cli acp --agent-engine=v3 must start), signed in. Set KIRO_BIN when kiro-cli is not on the server's PATH.

Install

npx -y @sohampatwardhan/kiro-mcp-server@latest

Claude Code

claude mcp add kiro -e KIRO_MCP_ROOTS=$HOME/code -- npx -y @sohampatwardhan/kiro-mcp-server@latest

Cursor, Claude Desktop, and other JSON configs

{
  "mcpServers": {
    "kiro": {
      "command": "npx",
      "args": ["-y", "@sohampatwardhan/kiro-mcp-server@latest"],
      "env": { "KIRO_MCP_ROOTS": "/Users/me/code" }
    }
  }
}

Codex

[mcp_servers.kiro]
command = "npx"
args = ["-y", "@sohampatwardhan/kiro-mcp-server@latest"]
env = { KIRO_MCP_ROOTS = "/home/me/code" }

Install the skills

The repository ships agent skills that teach agents when and how to use these tools: delegating a task to Kiro, choosing mode, model, effort, and permission handling, following a run live, collecting results and patches, and recovering from failures. Install them with the skills CLI:

npx skills add sohampatwardhan/kiro-mcp-server -g

Install one skill, or only for some agents:

npx skills add sohampatwardhan/kiro-mcp-server -g --skill kiro-orchestration
npx skills add sohampatwardhan/kiro-mcp-server -g -a claude-code -a codex

Each skill's SKILL.md carries a SemVer metadata.version, checked in CI by scripts/check-skill-versions.mjs, and CI installs the skills from the checkout into a throwaway HOME to test this exact path.

Environment variables

All are optional. An invalid value makes the server print the variable name and reason on stderr and exit with code 2. Booleans accept 1, true, yes, 0, false, no.

KIRO_API_KEY, when set in the server's environment, is inherited by headless runs only. No tool can read or set it.

Workspace trust

ACP has no method for trusting a workspace. Until a folder is trusted, Kiro does not load its custom agents, steering, MCP servers, skills, or workflows, and asks before every shell and MCP call. Trust each root once: run kiro-cli --v3 in the folder and choose Trust, continue. kiro_status reports the saved trust for every root (read-only, from Kiro's per-workspace permissions file) and warns for each untrusted one. Kiro never saves trust for your home directory.

Shell approvals

Shell approvals are off by default, as in claude-code-mcp-server: Kiro's requests to run commands (including tests and builds) are rejected at once and recorded as policy: "shell_disabled". To let the calling agent approve them one at a time, set KIRO_MCP_ALLOW_SHELL=1. To approve every non-shell request automatically as well, add KIRO_MCP_PERMISSIONS=allow.

Typical flow

1. kiro_status checks the CLI, sign-in, V3 engine, trust, and policy.

2. kiro_session_new (or kiro_session_load) attaches a session; kiro_session_configure picks mode (vibe, plan, spec, quick-spec, bug-fix, autonomous, or a custom agent), model, and effort.

3. kiro_prompt sends a prompt and waits up to wait_s. If the turn is still running, poll kiro_events (or kiro_stream_session) with the returned cursor until the status is completed, cancelled, or failed.

4. Answer pending_permissions with kiro_permission_respond. When the client supports MCP elicitation, the request is also shown to its user.

5. Steer with kiro_steer, stop with kiro_cancel, branch with kiro_session_fork or kiro_tangent, and close with kiro_session_close.

Tool reference

Resource: kiro-session://<session_id>/transcript returns a session's newest events as JSON. Subscribe with resources/subscribe to get notifications/resources/updated within a second of new events.

Errors

Development

npm ci
npm run build   # strict tsc is the static check
npm test        # builds, then node --test against the fake kiro-cli

Tests never run a real kiro-cli: test/fixtures/fake-kiro.mjs stands in for it through KIRO_BIN. See AGENTS.md for the architecture and rules.

Releasing

Bump version in package.json, merge, then push a matching tag (git tag v0.1.0 && git push origin v0.1.0). The release workflow checks the tag against package.json, builds, tests, publishes to npm with provenance through trusted publishing (GitHub OIDC, no NPM_TOKEN), creates a GitHub release, and mirrors the package to GitHub Packages.

Credits

Inspired by vanphappi/kiro-cli-mcp. No code was copied.

License

MIT