Linear MCP: AI-Native Project Management Integration

Your AI agents already write code, triage emails, and manage infrastructure. But when it comes to project management, they’re blind — unable to see the backlog, create issues, or update project status without manual copy-paste.

Linear MCP fixes this. It gives any MCP-compatible AI agent full, structured access to your Linear workspace.

What It Does

Linear MCP exposes Linear’s entire project management surface through the Model Context Protocol. AI agents can:

Core Work Management

• Issues — create (single or batch), update, search, delete, manage parent-child hierarchy, and create issue relations
• Projects — create, update, delete, search, create-with-issues, and associate with initiatives
• Comments — create threaded replies, update, delete, resolve/unresolve threads
• Milestones — full CRUD plus bulk create and search

Workflow and Discovery

• Teams, users, workflow states, labels, and cycles
• Free-text search with optional filters (team, project, assignee, state, priority, cycle)
• Exact issue identifier resolution (e.g., ENG-431) with fallback to ranked search

Integrations and Advanced Surfaces

• Attachments, webhooks, portfolio entities (initiatives, customers)
• Agent sessions and agent activities
• Runtime capability discovery and live diagnostics

Architecture

AI Agent (Claude / Codex / OpenClaw / Cline)
  -> MCP transport (stdio or HTTP)
    -> Linear MCP server
      -> Linear GraphQL API

Linear MCP enforces tool schemas at runtime before handler dispatch. Malformed payloads fail with structured validation errors at the MCP boundary — not deep in Linear’s API.

Guarded contracts — Critical issue workflows (single create, batch create, search) use audited raw GraphQL operations instead of SDK mutations, preventing SDK regressions from reaching your agents. Run npm run verify:linear-api-contracts to audit locally.

Structured telemetry — Every tool request emits stderr telemetry with tool name, transport, duration, and sanitized failure metadata for troubleshooting.

Authentication

API Key (simplest):

LINEAR_API_KEY=your_personal_access_token

OAuth (for shared or remote deployments):

1. Call linear_auth with your clientId, clientSecret, and redirectUri
2. Open the returned authorization URL
3. Call linear_auth_callback with the code and state

In stream mode, each MCP session gets its own isolated auth context.

Quick Start

# Install from npm
npx @kkaminsk/linear-mcp

# Or clone and build
git clone https://github.com/kkaminsk/linear-mcp.git
cd linear-mcp && npm install && npm run build

# Run with API key
LINEAR_API_KEY=your_key npm start

MCP client config:

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/path/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "your_personal_access_token"
      }
    }
  }
}

Who It’s For

• Development teams — AI agents that can triage, create, and update issues as part of their workflow
• Engineering managers — Automated project status updates, milestone tracking, and backlog grooming
• DevOps and SRE teams — AI agents that create incidents, link issues, and track resolution
• AI agent builders — Any MCP client that needs structured access to project management

GitHub: github.com/kkaminsk/linear-mcp

npm: @kkaminsk/linear-mcp