Linear MCP Server

A Model Context Protocol (MCP) server implementation that provides comprehensive access to Linear's issue tracking system through a standardized interface.

Features

Core Issue Management

• Create new issues and subissues with label support
• Update existing issues with full field modification
• Delete issues with validation
• Self-assign issues using 'me' keyword
• Advanced search with Linear's powerful filtering capabilities
• Filter issues by cycle (current, next, previous, or specific cycle)
• Add comments to issues with markdown support
• Query Linear issues by ID or key with optional relationships

Project Management

• List projects with filtering and pagination
• Project updates with health status tracking
• Project milestones - Create, update, delete milestones

Team & User Management

• List users in workspace or by team
• Get user details (supports "me" for current user)
• Team members with role information
• List teams with name/key filtering

Initiative Management

• List initiatives
• Create and update initiatives
• Link/unlink projects to initiatives

Document Management

• List documents (workspace or project-specific)
• Create and update documents
• Markdown content support

Cycle Management

• List cycles for a team
• Get cycle details
• Create and update cycles
• Filter issues by cycle

Workflow & Labels

• List workflow states for a team
• List labels (workspace or team-specific)
• Create and update labels

Attachments

• List attachments for an issue
• Get attachment details
• Create, update, and delete attachments
• Support for custom metadata and icons

Notifications (Inbox)

• List notifications for current user
• Get notification details
• Mark notifications as read (single or all)
• Archive, snooze, and unsnooze notifications
• Get unread notification count

Issue History

• Get complete change history for any issue
• Track state, assignee, priority, and label changes
• See who made each change and when

Prerequisites

• Node.js v18+ or Bun runtime
• Linear account with API access
• Linear API key (generate at Linear Settings > API)

Installation

Install from npm:

npm install -g @calltelemetry/linear-mcp

Or use directly with npx (no installation required):

npx @calltelemetry/linear-mcp

Configuration

Configure the MCP server in your preferred AI coding assistant. You'll need your Linear API key.

Using .env file (Recommended)

The server automatically loads environment variables from a .env file. Create ~/.env or .env in your project:

LINEAR_API_KEY=lin_api_xxxxxxxxxxxxx

Then configure your MCP client without the env block:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@calltelemetry/linear-mcp"]
    }
  }
}

Using inline environment variables

Alternatively, pass the API key directly in the MCP config:

OpenCode

Create or edit mcp.json in your project root or ~/.config/opencode/mcp.json globally:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@calltelemetry/linear-mcp"],
      "env": {
        "LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxx"
      }
    }
  }
}

Claude Code (Anthropic CLI)

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@calltelemetry/linear-mcp"],
      "env": {
        "LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxx"
      }
    }
  }
}

Or configure globally in ~/.claude/settings.json:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@calltelemetry/linear-mcp"],
      "env": {
        "LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxx"
      }
    }
  }
}

Claude Desktop

Edit the configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude Desktop\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@calltelemetry/linear-mcp"],
      "env": {
        "LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxx"
      }
    }
  }
}

Cline (VS Code Extension)

Edit the configuration file:

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@calltelemetry/linear-mcp"],
      "env": {
        "LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxx"
      }
    }
  }
}

Available MCP Tools (50+ tools)

Issue Tools

| Tool | Description | |------|-------------| | create_issue | Create a new issue or subissue | | update_issue | Update an existing issue | | get_issue | Get issue details with optional relationships | | search_issues | Search issues with advanced filters | | delete_issue | Delete an issue |

Team Tools

| Tool | Description | |------|-------------| | get_teams | List teams with optional filtering |

User Tools

| Tool | Description | |------|-------------| | get_users | List users in workspace or team | | get_user | Get user details (use "me" for self) | | get_team_members | List team members with roles |

Comment Tools

| Tool | Description | |------|-------------| | create_comment | Add a comment to an issue |

Project Tools

| Tool | Description | |------|-------------| | get_projects | List projects with filtering | | get_project_updates | Get project updates | | create_project_update | Create a project update |

Milestone Tools

| Tool | Description | |------|-------------| | get_milestones | List milestones (all or by project) | | get_milestone | Get milestone details | | create_milestone | Create a new milestone | | update_milestone | Update a milestone | | delete_milestone | Delete a milestone |

Initiative Tools

| Tool | Description | |------|-------------| | get_initiatives | List initiatives | | get_initiative | Get initiative details | | create_initiative | Create a new initiative | | update_initiative | Update an initiative | | add_project_to_initiative | Link a project to an initiative | | remove_project_from_initiative | Unlink a project |

Document Tools

| Tool | Description | |------|-------------| | get_documents | List documents | | get_document | Get document details | | create_document | Create a new document | | update_document | Update a document |

Cycle Tools

| Tool | Description | |------|-------------| | get_cycles | List cycles for a team | | get_cycle | Get cycle details | | create_cycle | Create a new cycle | | update_cycle | Update a cycle |

Workflow & Label Tools

| Tool | Description | |------|-------------| | get_workflow_states | List workflow states for a team | | get_labels | List labels (workspace or team) | | create_label | Create a new label | | update_label | Update a label |

Attachment Tools

| Tool | Description | |------|-------------| | get_attachments | List attachments for an issue | | get_attachment | Get attachment details | | create_attachment | Create an attachment on an issue | | update_attachment | Update an attachment | | delete_attachment | Delete an attachment |

Notification Tools (Inbox)

| Tool | Description | |------|-------------| | get_notifications | List notifications for current user | | get_notification | Get notification details | | mark_notification_read | Mark a notification as read | | mark_all_notifications_read | Mark all notifications as read | | archive_notification | Archive a notification | | snooze_notification | Snooze until a specified time | | unsnooze_notification | Unsnooze a notification | | get_unread_notification_count | Get count of unread notifications |

History Tools

| Tool | Description | |------|-------------| | get_issue_history | Get change history for an issue |

Tool Input Schemas

create_issue

{
  "teamId": "string",
  "title": "string",
  "description": "string",
  "parentId": "string",
  "status": "string",
  "priority": "number",
  "assigneeId": "string | 'me'",
  "labelIds": ["string"],
  "projectId": "string",
  "milestoneId": "string"
}

search_issues

{
  "query": "string",
  "includeRelationships": "boolean",
  "filter": {
    "priority": { "gte": "number" },
    "assignee": { "id": { "eq": "string" } },
    "state": { "type": { "eq": "started" } },
    "and": [{ }],
    "or": [{ }]
  },
  "projectId": "string",
  "projectName": "string"
}

create_milestone

{
  "projectId": "string",
  "name": "string",
  "description": "string",
  "targetDate": "string (ISO format)",
  "sortOrder": "number"
}

create_initiative

{
  "name": "string",
  "description": "string",
  "color": "string (hex)",
  "icon": "string",
  "sortOrder": "number",
  "targetDate": "string (ISO format)"
}

create_document

{
  "title": "string",
  "projectId": "string",
  "content": "string (markdown)",
  "icon": "string",
  "color": "string"
}

create_cycle

{
  "teamId": "string",
  "name": "string",
  "description": "string",
  "startsAt": "string (ISO format)",
  "endsAt": "string (ISO format)"
}

Technical Details

• Built with TypeScript in strict mode
• Uses Linear's official SDK (@linear/sdk v70)
• Uses MCP SDK (@modelcontextprotocol/sdk)
• Authentication via API tokens
• Comprehensive error handling
• Vite build system
• ESM modules throughout
• Type-safe operations

Error Handling

The server implements comprehensive error handling:

• Network error detection
• HTTP status code handling
• Input validation for all parameters
• Safe error propagation through MCP protocol
• Rate limit detection and handling
• Authentication error handling

Version History

• v0.5.0 - Full SDK parity: attachments, notifications/inbox, issue history
• v0.4.0 - Major expansion with milestones, initiatives, documents, users, cycles, and labels
• v0.3.0 - Added project updates and health status
• v0.2.0 - Added cycle filtering and advanced search
• v0.1.0 - Initial release with basic issue operations

License

This project is licensed under the MIT License - see the LICENSE file for details.

Originally created by Dimosthenis Kaponis, expanded by CallTelemetry.