Claude Code + Linear MCP Integration Guide 2026

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Workflow

Connect Claude Code to Linear’s project management system through the Model Context Protocol (MCP). This enables Claude Code to read issues, create tasks, update statuses, and link PRs to issues directly from your terminal.

Expected time: 15 minutes Prerequisites: Linear account with API key, Claude Code CLI installed, Node.js 18+

Setup

1. Get Your Linear API Key

# Navigate to Linear → Settings → API → Personal API Keys
# Create a new key with these scopes:
# - issues:read, issues:write
# - projects:read
# - teams:read
# - comments:write

# Store it securely
export LINEAR_API_KEY="lin_api_xxxxxxxxxxxxxxxxxxxxx"

2. Install the Linear MCP Server

npm install -g @anthropic-ai/mcp-server-linear

This installs the official MCP server that bridges Claude Code and Linear’s API.

3. Configure Claude Code MCP Settings

// ~/.claude/settings.json
{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-linear"],
      "env": {
        "LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

4. Create a Project CLAUDE.md with Linear Context

# Project: MyApp Backend

## Linear Integration
- Team: Backend (key: BACK)
- Current sprint: Sprint 24
- Label conventions: bug, feature, tech-debt, dx
- Estimate scale: 1=trivial, 2=small, 3=medium, 5=large, 8=epic

## Workflow
- When fixing a bug, reference the Linear issue ID in commits
- Format: "fix(BACK-123): description"
- Move issues to "In Progress" when starting work
- Move to "In Review" when PR is opened

5. Verify

claude

> List my assigned Linear issues for this sprint
# Expected output:
# BACK-142: Fix authentication timeout (In Progress, estimate: 3)
# BACK-145: Add rate limiting to /api/v2 (Todo, estimate: 5)
# BACK-147: Update error response format (Todo, estimate: 2)

Usage Example

Complete workflow from issue to implementation using Claude Code with Linear:

# Start Claude Code
claude

# Check what to work on
> What's the highest priority unassigned issue in the Backend team?

Claude Code queries Linear via MCP:

Found: BACK-156 "Database connection pool exhaustion under load"
Priority: Urgent | Estimate: 5 | Labels: bug, production
Description: Under sustained load (>500 req/s), the connection pool
exhausts all connections and requests start failing with timeout errors.

Start working on it:

> Assign BACK-156 to me and move it to "In Progress"

Claude Code updates Linear:

Done. BACK-156 assigned to you and moved to "In Progress".

Now implement the fix with full context:

> Based on BACK-156, analyze our database connection configuration
> and implement a fix for pool exhaustion. Check src/db/ for the
> current setup.

Claude Code reads your code and generates:

// src/db/pool-config.ts
import { Pool, PoolConfig } from "pg";

interface HealthyPoolConfig extends PoolConfig {
  maxConnections: number;
  minConnections: number;
  acquireTimeoutMs: number;
  idleTimeoutMs: number;
  reapIntervalMs: number;
}

const DEFAULT_CONFIG: HealthyPoolConfig = {
  maxConnections: 20,
  minConnections: 5,
  acquireTimeoutMs: 10000,
  idleTimeoutMs: 30000,
  reapIntervalMs: 1000,
  host: process.env.DB_HOST,
  port: parseInt(process.env.DB_PORT || "5432"),
  database: process.env.DB_NAME,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
};

export function createPool(overrides?: Partial<HealthyPoolConfig>): Pool {
  const config = { ...DEFAULT_CONFIG, ...overrides };

  const pool = new Pool({
    max: config.maxConnections,
    min: config.minConnections,
    idleTimeoutMillis: config.idleTimeoutMs,
    connectionTimeoutMillis: config.acquireTimeoutMs,
    host: config.host,
    port: config.port,
    database: config.database,
    user: config.user,
    password: config.password,
  });

  pool.on("error", (err) => {
    console.error("Unexpected pool error:", err.message);
  });

  pool.on("connect", () => {
    pool.query("SET statement_timeout = '30s'");
  });

  return pool;
}

After implementing and testing:

> Add a comment to BACK-156 with the fix summary and move it to "In Review"

# Claude Code posts to Linear:
# "Fixed by adjusting pool config: max=20, min=5, added connection timeout
#  of 10s, idle timeout 30s, and statement timeout 30s per connection.
#  PR: #234"

Common Issues

Why This Matters

Developers using Linear + Claude Code MCP integration report closing issues 25% faster by eliminating manual status updates and context switching between browser and terminal.