Kiro CLI MCP Server

A Model Context Protocol (MCP) server that enables IDE agents like Cursor and Windsurf to orchestrate kiro-cli with advanced session management, process pooling, and robust error handling.

Overview

Kiro CLI MCP Server bridges the gap between IDE agents and kiro-cli by providing a standardized MCP interface with enterprise-grade features:

• 10x Performance Improvement: Process pooling reduces response time from ~500ms to ~50ms
• Multi-Session Management: Isolated contexts for different projects/workflows
• Production-Ready Reliability: Comprehensive error handling, timeout management, and process cleanup
• Mock Mode: Development and testing without kiro-cli dependency

Features

Core Capabilities

• Chat Integration: Send messages to kiro-cli and receive AI responses
• Session Management: Create, switch, and manage multiple isolated sessions
• Command Execution: Execute kiro-cli commands (/help, /mcp, etc.)
• Custom Agents: Use and list available custom agents
• History Management: Store and retrieve conversation history per session
• Async Operations: Background task execution with progress polling

Performance & Reliability

• Process Pooling: Reuse warm kiro-cli processes for 10x faster responses
• Process Tree Cleanup: Prevent orphaned processes across platforms
• Automatic Fallback: Mock mode when kiro-cli unavailable
• Timeout Handling: Configurable timeouts with graceful cleanup
• Session Isolation: Per-project working directories and conversation state

Installation

Prerequisites

• Python 3.10+
• kiro-cli installed and available in PATH (for full functionality - uses mock mode if unavailable)

From Source (Current Method)

git clone https://github.com/your-org/kiro-cli-mcp.git
cd kiro-cli-mcp
pip install -e .

Via pip (After PyPI Publication)

# Will be available after publishing to PyPI
pip install kiro-cli-mcp

Via uvx (After PyPI Publication)

# Will be available after publishing to PyPI
uvx install kiro-cli-mcp

Configuration

IDE Integration

Add to your IDE's MCP configuration file:

Cursor/Claude Desktop (~/.config/claude-desktop/mcp.json):

{
  "mcpServers": {
    "kiro-cli-mcp": {
      "command": "uvx",
      "args": ["kiro-cli-mcp"],
      "env": {
        "KIRO_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Windsurf (.windsurf/mcp.json):

{
  "mcpServers": {
    "kiro-cli-mcp": {
      "command": "python",
      "args": ["-m", "kiro_cli_mcp"],
      "env": {
        "KIRO_MCP_CLI_PATH": "/usr/local/bin/kiro-cli",
        "KIRO_MCP_POOL_SIZE": "5"
      },
      "autoApprove": [
        "kiro_session_list",
        "kiro_agents_list",
        "kiro_history"
      ]
    }
  }
}

Environment Variables

Variable	Description	Default
KIRO_MCP_CLI_PATH	Path to kiro-cli executable	kiro-cli
KIRO_MCP_COMMAND_TIMEOUT	Command timeout (seconds) - IDE-optimized	30
KIRO_MCP_MAX_SESSIONS	Maximum concurrent sessions	10
KIRO_MCP_SESSION_TIMEOUT	Session idle timeout (seconds)	300
KIRO_MCP_CLEANUP_INTERVAL	Session cleanup check interval (seconds)	30
KIRO_MCP_LOG_LEVEL	Logging level	INFO
KIRO_MCP_DEFAULT_MODEL	Default AI model for kiro-cli	claude-opus-4.5
KIRO_MCP_DEFAULT_AGENT	Default agent to use	kiro_default
KIRO_MCP_LOG_RESPONSE	Log full CLI responses for debugging	true
KIRO_MCP_POOL_SIZE	Process pool size	5
KIRO_MCP_POOL_ENABLED	Enable process pooling	true
KIRO_MCP_POOL_IDLE_TIME	Process idle time before recycling (seconds)	300
KIRO_MCP_POOL_MAX_USES	Max uses per process before recycling	100
KIRO_MCP_MAX_ASYNC_TASKS	Maximum concurrent async tasks	100
KIRO_MCP_TASK_TTL	Task result TTL (seconds)	3600

Available MCP Tools

Session Management

• kiro_session_create - Create new session with optional agent and working directory
• kiro_session_list - List all active sessions
• kiro_session_switch - Switch to specific session
• kiro_session_end - End a session
• kiro_session_clear - Clear session history files
• kiro_session_save - Save session to file

Chat & Commands

• kiro_chat - Send chat message and get AI response
• kiro_command - Execute kiro-cli commands (/help, /mcp, etc.)
• kiro_agents_list - List available custom agents

History Management

• kiro_history - Get conversation history for session
• kiro_history_clear - Clear conversation history

Async Operations

• kiro_chat_async - Start background chat task
• kiro_task_status - Poll task progress and results
• kiro_task_cancel - Cancel running task
• kiro_task_list - List active tasks

Monitoring

• kiro_pool_stats - Get process pool performance statistics

Usage Examples

Basic Chat

# Create session for project
await mcp_client.call_tool("kiro_session_create", {
    "working_directory": "/path/to/project",
    "agent": "code-reviewer"
})

# Send message
response = await mcp_client.call_tool("kiro_chat", {
    "message": "Analyze this codebase and suggest improvements"
})

Multi-Project Workflow

# Project A
session_a = await mcp_client.call_tool("kiro_session_create", {
    "working_directory": "/projects/frontend",
    "agent": "react-expert"
})

# Project B  
session_b = await mcp_client.call_tool("kiro_session_create", {
    "working_directory": "/projects/backend", 
    "agent": "python-expert"
})

# Switch between projects
await mcp_client.call_tool("kiro_session_switch", {
    "session_id": session_a["session_id"]
})

Async Operations

# Start long-running task
task = await mcp_client.call_tool("kiro_chat_async", {
    "message": "Generate comprehensive test suite"
})

# Poll for progress
while True:
    status = await mcp_client.call_tool("kiro_task_status", {
        "task_id": task["task_id"]
    })
    if status["status"] == "completed":
        break
    await asyncio.sleep(1)

Architecture

MCP Protocol Integration

• Server: Built on official MCP SDK (mcp.server.Server)
• Transport: JSON-RPC 2.0 over stdio
• Tools: 16 registered tools with schema validation
• Resources: Minimal resource handling for extensibility

Process Management

IDE Agent → MCP Server → Process Pool → kiro-cli instances
                    ↓
              Session Manager → Isolated contexts per project

Key Components

• SessionManager: Multi-session isolation and lifecycle management
• ProcessPool: Warm process reuse for 10x performance improvement
• CommandExecutor: Robust command execution with timeout handling
• StreamingTaskManager: Async task execution with progress polling

Performance Optimizations

1. Process Pooling: Reuse warm kiro-cli processes
2. Session Affinity: Route requests to appropriate process
3. Intelligent Cleanup: Remove idle/unhealthy processes
4. Mock Mode: Fast responses during development

Development

Setup

git clone https://github.com/your-org/kiro-cli-mcp.git
cd kiro-cli-mcp
pip install -e ".[dev]"

Testing

# Run all tests
pytest

# With coverage
pytest --cov=kiro_cli_mcp --cov-report=html

# Property-based tests
pytest tests/test_config.py -v

Code Quality

# Format code
ruff format .

# Lint
ruff check .

# Type checking
mypy src/

Running Server

# Development mode with debug logging
python -m kiro_cli_mcp --log-level DEBUG

# With custom config
python -m kiro_cli_mcp --config config.json

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

Troubleshooting

kiro-cli Not Found

Server automatically enables mock mode if kiro-cli is unavailable:

# Check kiro-cli availability
which kiro-cli

# Set custom path
export KIRO_MCP_CLI_PATH=/custom/path/to/kiro-cli

# Verify server mode
python -m kiro_cli_mcp --log-level DEBUG
# Look for: "✅ kiro-cli is available" or "❌ kiro-cli not available: enabling mock mode"

Performance Issues

# Verify process pooling is enabled
python -m kiro_cli_mcp --log-level DEBUG
# Look for: "🔄 Using pooled process execution"

# Check pool statistics
# Use kiro_pool_stats tool to monitor performance

Session Management

# Increase session limits
export KIRO_MCP_MAX_SESSIONS=20
export KIRO_MCP_SESSION_TIMEOUT=7200  # 2 hours

# Clear stuck sessions
# Sessions auto-cleanup after timeout

Process Cleanup

If you encounter orphaned processes:

# Unix/Linux/macOS
pkill -f kiro-cli

# Windows  
taskkill /F /IM kiro-cli.exe

# Check process groups (Unix)
ps -eo pid,pgid,cmd | grep kiro

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki