copilot-cli-mcp

MCP server that wraps GitHub Copilot CLI's ACP protocol. Spawns copilot --acp, manages sessions over stdio, auto-handles permissions, collects streamed events, and exposes Copilot through 4 MCP tools.

What it does

• Delegates coding tasks to any Copilot model (GPT-5.x, Claude, etc.)
• Built-in agents: code review, research, explore, task runner
• Rubber-duck critique mode for analysis-only feedback
• Fleet mode for parallel task decomposition
• Async execution with task tracking
• Multi-turn sessions with model/mode switching
• Git-aware: branch creation and isolated worktrees
• Conversation transcripts included in results

Requirements

• Node.js 22+
• GitHub Copilot CLI installed and authenticated (copilot login)

Install

npm install
npm run build

MCP client configuration

Add to your .mcp.json or MCP settings:

{
  "mcpServers": {
    "copilot": {
      "command": "node",
      "args": ["/path/to/copilot-cli-mcp/dist/index.js"]
    }
  }
}

Environment

| Variable | Default | Purpose | |---|---|---| | COPILOT_CLI_PATH | copilot | Path to the Copilot CLI binary | | COPILOT_MCP_LOG_LEVEL | info | Log level: debug, info, warn, error |

Tools

copilot — the universal work tool

Run any task, select agents, enable fleet/critique/async modes.

copilot({ prompt: "Fix the auth bug" })
copilot({ prompt: "Fix the auth bug", model: "gpt-5.4", reasoning_effort: "high" })
copilot({ prompt: "Review changes", agent: "code-review" })
copilot({ prompt: "How is auth implemented?", agent: "research" })
copilot({ prompt: "How many test files?", agent: "explore" })
copilot({ prompt: "run tests", agent: "task", command: "npm test" })
copilot({ prompt: "Refactor the API layer", fleet: true })
copilot({ prompt: "function add(a,b){return a-b}", critique: true })
copilot({ prompt: "Fix the bug", async: true })  // returns { task_id }
copilot({ prompt: "Fix the bug", branch: "fix/bug", worktree: true })
copilot({ prompt: "Continue", session_id: "abc-123" })

Key parameters: | Param | Purpose | |---|---| | prompt | The task (required) | | model | Model ID: gpt-5-mini, gpt-5.4, claude-opus-4.6, etc. | | reasoning_effort | low, medium, high, xhigh | | agent | Built-in agent: code-review, research, explore, task | | fleet | Parallel task decomposition | | critique | Rubber-duck subagent for analysis-only feedback | | async | Run in background, returns { task_id } | | branch | Git branch to create/checkout | | worktree | Isolate work in a git worktree | | session_id | Resume an existing session | | provider | BYOK: { type, baseUrl, apiKey } | | system_message | { mode: "append"\|"replace", content } | | tools_policy | "all", "read-only", or allow list | | attachments | Files, directories, selections, images | | working_dir | Working directory for the session |

copilot_tasks — manage async tasks

copilot_tasks({ action: "list" })
copilot_tasks({ action: "check", task_id: "..." })
copilot_tasks({ action: "cancel", task_id: "..." })

copilot_session — control sessions

copilot_session({ session_id: "...", action: "send", prompt: "Follow up" })
copilot_session({ session_id: "...", action: "switch_model", model: "gpt-5.4" })
copilot_session({ session_id: "...", action: "set_mode", mode: "autopilot" })
copilot_session({ session_id: "...", action: "get_plan" })
copilot_session({ session_id: "...", action: "set_plan", content: "## Plan\n..." })
copilot_session({ session_id: "...", action: "read_file", path: "output.json" })
copilot_session({ session_id: "...", action: "metrics" })
copilot_session({ session_id: "...", action: "compact" })
copilot_session({ session_id: "...", action: "transcript" })
copilot_session({ session_id: "...", action: "destroy" })

copilot_info — discovery

copilot_info({ query: "models" })
copilot_info({ query: "agents" })
copilot_info({ query: "tools" })
copilot_info({ query: "sessions" })
copilot_info({ query: "quota" })

How it works

MCP Client (Claude Code, IDE, etc.)
    |
    |-- copilot({ prompt, model, ... })
    v
MCP Server (this project)
    |-- Spawns copilot --acp process
    |-- Creates session via JSON-RPC
    |-- Sends prompt, consumes event stream
    |-- Auto-handles permissions (based on tools_policy)
    |-- Collects response, tool calls, file changes, transcript
    |-- Returns structured result
    v
Copilot ACP (child process)
    |-- Routes to selected model (GPT-5.x, Claude, etc.)
    |-- Executes agentic loop with tools
    |-- Streams events back

Development

npm run check   # strict typecheck
npm test         # unit tests
npm run build    # compile

Project layout

src/
  acp/           ACP client, types, events, protocol
  session/       Session manager, event collector, permission handler
  tasks/         Async task tracking
  tools/         MCP tool schemas and registration
  util/          Errors and logging
  server.ts      MCP server construction (4 tools)
  runtime.ts     High-level implementation
  index.ts       Entry point