Linear MCP Server

MCP (Model Context Protocol) server for integrating Linear with Claude Code and other MCP clients.

Features

• Issue Management: Create, update, and query Linear issues
• Project Planning: Create projects and break them down into milestones
• Status Tracking: Update issue status through workflow states
• Progress Updates: Add comments and progress notes to issues
• Team Context: Query team information and workflow states

Installation

This project uses uv for dependency management.

# Install dependencies
uv sync

# Or with pip
pip install -e .

Configuration

1. Get your Linear API key:

   • Go to Linear Settings > Account > Security & Access
   • Create a new Personal API key
   • Choose appropriate permissions (Read, Write, Create issues, Create comments)

2. Create .env file:

   cp .env.example .env
   # Edit .env and add your LINEAR_API_KEY
   

Usage with Claude Code

Add to your Claude Code configuration (~/.claude/config.json or project .claude/mcp-servers.json):

{
  "mcpServers": {
    "linear": {
      "command": "uv",
      "args": ["run", "linear-mcp-server"],
      "cwd": "/Users/devonshurick/dev/personal/linear-mcp-server",
      "env": {
        "LINEAR_API_KEY": "lin_api_xxxxxxxxxxxx"
      }
    }
  }
}

Or use environment variables:

{
  "mcpServers": {
    "linear": {
      "command": "uv",
      "args": ["run", "linear-mcp-server"],
      "cwd": "/Users/devonshurick/dev/personal/linear-mcp-server"
    }
  }
}

Then set LINEAR_API_KEY in your .env file.

Available Tools

Issue Management

• linear_create_issue - Create a new issue

  • Parameters: title, description, team_id, optional: project_id, state_id, priority, assignee_id

• linear_update_issue - Update an existing issue

  • Parameters: issue_id, optional: state_id, title, description, priority

• linear_list_issues - List issues for a team

  • Parameters: team_id, optional: status_filter, assignee_id, limit

• linear_add_comment - Add a comment to an issue

  • Parameters: issue_id, body

Team & Workflow

• linear_get_teams - List available teams

• linear_get_workflow_states - Get workflow states for a team

  • Parameters: team_id

Projects (Coming Soon)

• linear_create_project - Create a new project with milestones
• linear_list_projects - List projects

Development

# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Format code
uv run black .

# Lint
uv run ruff check .

Architecture

src/linear_mcp/
├── __init__.py
├── server.py         # MCP server implementation
├── linear_client.py  # Linear GraphQL API client
└── tools.py          # Tool definitions for MCP

Use Cases

1. Task Execution with Progress Tracking

   • Claude receives task → Creates Linear issue → Works on task → Updates issue with progress → Marks done

2. Project Planning

   • User describes goal → Claude creates project → Breaks into milestones → Creates task issues → Links dependencies

3. Dynamic Prioritization

   • Claude reviews backlog → Analyzes priorities → Proposes changes → Updates issues after approval

Linear API Reference

• Linear GraphQL API
• API Schema
• Rate Limits: 1,500 requests/hour per API key

License

MIT