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

LINEAR_API_KEY=your_api_key  # Your Linear API token

Installation & Setup

1. Clone the repository:

git clone [repository-url]
cd linear-mcp

2. Install dependencies and build:

bun install
bun run 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:

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/absolute/path/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "your_api_key"
      }
    }
  }
}

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:

bun run dev

Build project:

bun run build

Available MCP Tools

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

create_issue

Create a new Linear issue or subissue.

Input Schema:

{

  "teamId": "string",     

  "title": "string",      

  "description": "string",

  "parentId": "string",   

  "status": "string",

  "priority": "number",   

  "assigneeId": "string | 'me'",

  "labelIds": ["string"]  

}

update_issue

Update an existing Linear issue.

Input Schema:

{

  "issueId": "string",    

  "title": "string",

  "description": "string",

  "status": "string",     // Expects status NAME (e.g., "In Progress"). Must be valid for the issue's team.

  "priority": "number",   // Expects 0 (None) to 4 (Low).

  "assigneeId": "string | 'me'",

  "labelIds": ["string"],

  "cycleId": "string"

}

get_issue

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

Input Schema:

{

  "issueId": "string",

  "includeRelationships": "boolean"  

}

search_issues

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

Input Schema:

{

  "query": "string",

  "includeRelationships": "boolean",

  "filter": {

    "title": { "contains": "string", "eq": "string", ... },

    "description": { "contains": "string", "eq": "string", ... },

    "priority": { "gte": "number", "lt": "number", ... },

    "estimate": { "eq": "number", "in": ["number"], ... },

    "dueDate": { "lt": "string", "gt": "string", ... },

    "createdAt": { "gt": "P2W", "lt": "2024-01-01", ... },

    "updatedAt": { "gt": "P1M", ... },

    "completedAt": { "null": true, ... },

    "assignee": { "id": { "eq": "string" }, "name": { "contains": "string" } },

    "creator": { "id": { "eq": "string" }, "name": { "contains": "string" } },

    "team": { "id": { "eq": "string" }, "key": { "eq": "string" } },

    "state": { "type": { "eq": "started" }, "name": { "eq": "string" } },

    "labels": { "name": { "in": ["string"] }, "every": { "name": { "eq": "string" } } },

    "project": { "id": { "eq": "string" }, "name": { "contains": "string" } },

    "and": [{ / filters / }],

    "or": [{ / filters / }],

    "assignedTo": "string | 'me'",

    "createdBy": "string | 'me'"

  },

  "projectId": "string",

  "projectName": "string"

}

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:

{

  "nameFilter": "string"  

}

delete_issue

Delete an existing Linear issue.

Input Schema:

{

  "issueId": "string"

}

create_comment

Create a new comment on a Linear issue.

Input Schema:

{

  "issueId": "string",

  "body": "string"

}

get_projects

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

Input Schema:

{

  "nameFilter": "string",

  "includeArchived": "boolean",

  "first": "number",

  "after": "string"

}

get_project_updates

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

Input Schema:

{

  "projectId": "string",

  "includeArchived": "boolean",

  "first": "number",

  "after": "string",

  "createdAfter": "string",

  "createdBefore": "string",

  "userId": "string | 'me'",

  "health": "string"

}

create_project_update

Create a new update for a Linear project.

Input Schema:

{

  "projectId": "string",

  "body": "string",

  "health": "onTrack | atRisk | offTrack",

  "isDiffHidden": "boolean"

}

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

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.