Legible Linear MCP Server

How to use

You connect Claude Code to Linear through the MCP server to access Linear data and perform actions such as creating and updating issues, comments, projects, cycles, teams, and users. Use OAuth to authenticate once and switch between multiple Linear workspaces as needed. The server automatically handles token refreshes, API rate limits, and complex queries, so you can focus on your work.

How to install

Prerequisites: you need Node.js and npm installed on your machine.

# 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

Additional setup and usage

Configure Claude Code to load the Linear MCP server using a local stdio connection. Provide the path to the built MCP server and start Claude Code to enable the integration.

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

Authenticate and manage workspaces

Authenticate via OAuth to enable seamless token management and access to multiple Linear workspaces. You can add and switch between workspaces as needed.

# Opens browser for OAuth login
lmcp auth login

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

Environment and credentials

Two authentication options exist: OAuth (recommended) and an API key (legacy). OAuth credentials take priority over environment variables.

# OAuth workflow (recommended)
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`.

Environment variables (legacy method)

You can also use an API key directly by setting an environment variable. If both methods are available, OAuth takes precedence.

export LINEAR_API_KEY=lin_api_YOUR_KEY_HERE

CLI reference at a glance

Common commands for managing authentication and server status include:

lmcp auth login      # Authenticate with Linear via OAuth
lmcp auth logout     # Remove a workspace's credentials
lmcp auth list       # List all connected workspaces
lmcp auth switch     # Switch active workspace
lmcp 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
"

Helpfully, what the MCP provides

Core capabilities include full CRUD across Linear data (issues, comments, projects, cycles, teams, users), human-readable identifiers, smart chunking for large content, and Markdown export of issues with all comments. The server automatically handles token refresh, rate limiting with exponential backoff, and complex queries by splitting them as needed.

Troubleshooting and notes

If you encounter specific errors, the server automatically adapts in common cases. For example, it handles cases like missing field memberships by routing through GraphQL operations, and it splits oversized queries to respect complexity limits. If you experience persistent rate-limiting, consider reducing request frequency or batching operations.

Security and best practices

Prefer OAuth authentication for automatic token refreshing and secure management of workspace credentials. Keep API keys as a fallback and store credentials in the recommended secure location.