Legible Linear MCP

An MCP server that connects Claude Code to Linear with OAuth authentication and multi-workspace support.

Quick Start

1. Install

# Clone and build
git clone https://github.com/bleugreen/linear-mcp.git
cd linear-mcp
npm install
npm run build

# Install CLI globally (optional, for easy auth management)
npm link

2. Authenticate

# Opens browser for OAuth login
lmcp auth login

# Or if not installed globally:
node dist/cli.js auth login

3. Configure Claude Code

Add to your Claude Code MCP settings (~/.claude.json or via Claude Code settings):

{
  "mcpServers": {
    "linear-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/linear-mcp/dist/mcp-server.js"]
    }
  }
}

Restart Claude Code and you're ready to go!

Authentication

OAuth (Recommended)

OAuth provides a seamless authentication experience with automatic token refresh:

lmcp auth login      # Authenticate with Linear
lmcp auth status     # Check current auth status
lmcp auth list       # List connected workspaces
lmcp auth switch     # Switch active workspace
lmcp auth logout     # Remove a workspace

Credentials are stored securely in ~/.linear-mcp/credentials.json.

Multi-Workspace Support

Connect to multiple Linear workspaces and switch between them:

# Add first workspace
lmcp auth login

# Add another workspace (will show consent screen)
lmcp auth login

# Switch between them
lmcp auth switch my-company
lmcp auth switch side-project

Environment Variable (Legacy)

You can also use an API key directly:

export LINEAR_API_KEY=lin_api_YOUR_KEY_HERE

Note: OAuth credentials take priority over the environment variable.

CLI Reference

lmcp <command> [options]

Commands:
  auth login       Authenticate with Linear via OAuth
  auth logout      Remove a workspace's credentials
  auth list        List all connected workspaces
  auth switch      Switch active workspace
  auth status      Show current authentication status
  serve            Start the MCP server (default)
  help             Show help message

Environment Variables:
  LINEAR_API_KEY       Use API key instead of OAuth (fallback)
  LINEAR_WORKSPACE     Override active workspace for session
  LINEAR_CLIENT_ID     Use custom OAuth app client ID
  LINEAR_CLIENT_SECRET Use custom OAuth app client secret

Features

Core Capabilities

Full CRUD: Issues, comments, projects, cycles, teams, users
Human-Readable IDs: Use team keys (TEAM), issue identifiers (TEAM-123), project names, user emails
Smart Chunking: Automatically splits large content across multiple comments
Markdown Export: Get full issue content with all comments in clean markdown

Reliability

Auto Token Refresh: OAuth tokens refresh automatically before expiry
Rate Limiting: Respects Linear's 1,500 req/hr limit with exponential backoff
Query Splitting: Handles Linear's 10,000 complexity limit automatically

Troubleshooting

"Field membership argument userId required"

The server handles this automatically by using raw GraphQL queries for affected endpoints.

"Query too complex"

The server automatically splits complex queries. If you still see this error, please file an issue.

SSE Connection Drops

The server sends heartbeats every 15 seconds. Check your proxy/firewall timeout settings.

Rate Limiting

The server implements exponential backoff. If you're hitting limits frequently, consider reducing request frequency or batch operations.

linear-mcp