https://github.com/bleugreen/linear-mcp
https://github.com/bleugreen/linear-mcp
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/bleugreen/linear-mcp
- Owner: bleugreen
- Created: 2025-07-27T04:55:50.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-27T05:08:23.000Z (11 months ago)
- Last Synced: 2025-07-27T07:18:45.559Z (11 months ago)
- Language: TypeScript
- Size: 143 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Legible Linear MCP
An MCP server that connects Claude Code to Linear with OAuth authentication and multi-workspace support.
## Quick Start
### 1. Install
```bash
# 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
```bash
# 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):
```json
{
"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:
```bash
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:
```bash
# 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:
```bash
export LINEAR_API_KEY=lin_api_YOUR_KEY_HERE
```
Note: OAuth credentials take priority over the environment variable.
## CLI Reference
```
lmcp [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
- [Linear API Documentation](https://developers.linear.app)
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io)
- [Linear TypeScript SDK](https://github.com/linear/linear)
## 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.