Handles Linear's GraphQL API complexity limits by automatically splitting complex queries into multiple simpler ones and assembling results transparently.

Bridges with Linear's GraphQL API, providing full CRUD operations for issues, comments, projects, cycles, teams, and users. Features include smart content chunking, human-readable identifiers, markdown export, and real-time updates via webhooks and SSE.

Enables exporting Linear issues with all comments in clean markdown format and handles markdown content when creating or updating issues and comments.

Requires Node.js 18+ as runtime environment for the server.

Utilizes Pino for structured JSON logging to enhance observability of server operations and troubleshooting.

Provides metrics for monitoring server performance, including RPC requests, latency, rate limiting, and active connections, accessible at the /metrics endpoint.

Leverages TypeScript with Linear's official SDK for full type safety across all API operations.

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!

Related MCP server: Linear MCP Server

🔐 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

🔗 Related Links

🐛 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 Server