Linear MCP Server

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

Features

• Create new issues and subissues with label support

• Retrieve the list of linear projects

• Retrieve the project updates

• Create a new project update with health status

• Update existing issues with full field modification

• Delete issue 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 by UUID or number)

• Add comments to issues with markdown support

• Query Linear issues by ID or key with optional relationships

• Search issues using custom queries with enhanced metadata

• Type-safe operations using Linear's official SDK

• Comprehensive error handling

• Rate limit handling

• Clean data transformation

• Parent/child relationship tracking with team inheritance

• Label management and synchronization

Prerequisites

• Bun runtime (v1.0.0 or higher)

• Linear account with API access

Environment Variables

Installation & Setup

1. Clone the repository:

2. Install dependencies and build:

3. Configure the MCP server:

Edit the appropriate configuration file:

macOS:

• Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

• Cline: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

• Claude Desktop: %APPDATA%\Claude Desktop\claude_desktop_config.json

Linux:

• Cline: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

• Claude Desktop: sadly doesn't exist yet

Add the following configuration under the mcpServers object:

4. Restart the MCP server.

Within Cline's MCP settings, restart the MCP server. Restart Claude Desktop to load the new MCP server.

Development

Run development server:

Build project:

Available MCP Tools

For detailed usage examples of all tools, see USAGE.md.

create_issue

Create a new Linear issue or subissue.

Input Schema:

update_issue

Update an existing Linear issue.

Input Schema:

get_issue

Get detailed information about a specific Linear issue with optional relationships.

Input Schema:

search_issues

Search for Linear issues using a query string and advanced filters. Supports Linear's powerful filtering capabilities.

Input Schema:

Supported Comparators:

• String fields: eq, neq, in, nin, contains, startsWith, endsWith (plus case-insensitive variants)

• Number fields: eq, neq, lt, lte, gt, gte, in, nin

• Date fields: eq, neq, lt, lte, gt, gte (supports ISO 8601 durations)

get_teams

Get a list of Linear teams with optional name/key filtering.

Input Schema:

delete_issue

Delete an existing Linear issue.

Input Schema:

create_comment

Create a new comment on a Linear issue.

Input Schema:

get_projects

Get a list of Linear projects with optional name filtering and pagination.

Input Schema:

get_project_updates

Get project updates for a given project ID with optional filtering parameters.

Input Schema:

create_project_update

Create a new update for a Linear project.

Input Schema:

Technical Details

• Built with TypeScript in strict mode

• Uses Linear's official SDK (@linear/sdk)

• Uses MCP SDK (@modelcontextprotocol/sdk 1.4.0)

• Authentication via API tokens

• Comprehensive error handling

• Rate limiting considerations

• Bun runtime for improved performance

• ESM modules throughout

• Vite build system

• Type-safe operations

• Data cleaning features:

  • Issue mention extraction (ABC-123 format)

  • User mention extraction (@username format)

  • Markdown content cleaning

  • Content optimization for AI context

• Self-assignment support:

  • Automatic current user resolution

  • 'me' keyword support in create/update operations

  • Efficient user ID caching

• Advanced search capabilities:

  • Comprehensive filtering with Linear's API

  • Support for all field comparators

  • Relationship filtering

  • Logical operators (and, or)

  • Relative date filtering

  • Filter by assignee/creator (including self)

  • Support for specific user IDs

  • Project filtering by ID or name

  • Efficient query optimization

• Project management features:

  • Project listing with filtering and pagination

  • Project update creation with health status tracking

  • Project update retrieval with filtering options

Error Handling

The server implements a comprehensive error handling strategy:

• Network error detection and appropriate messaging

• HTTP status code handling

• Detailed error messages with status codes

• Error details logging to console

• Input validation for all parameters

• Label validation and synchronization

• Safe error propagation through MCP protocol

• Rate limit detection and handling

• Authentication error handling

• Invalid query handling

• Team inheritance validation for subissues

• User resolution validation

• Search filter validation

LICENCE

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