MCP HubMCP Hub
cosmix

linear-mcp

by: cosmix

A Model Context Protocol server for Linear.

26created 24/01/2025
Visit
Protocol

📌Overview

Purpose: The Linear MCP Server aims to provide a standardized interface for accessing Linear's issue tracking system.

Overview: This implementation of the Model Context Protocol (MCP) enables users to efficiently interact with Linear's features, including issue tracking, project updates, and advanced searching capabilities. Built with TypeScript and Linear's official SDK, it emphasizes type safety, robust error handling, and self-assignment functionalities.

Key Features:

  • Issue Management: Create, update, and delete issues with support for labels, prioritization, and self-assignment using the 'me' keyword.

  • Project and Update Handling: Retrieve project lists and updates while allowing the creation of new project updates with health status.

  • Advanced Search Functionality: Perform detailed searches across issues using powerful filters and criteria, enhancing the ability to find relevant information quickly.

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 project updates
  • Create a new project update with health status
  • 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 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 and 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 according to your OS:

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: (not available)

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",
  "priority": "number",
  "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 and rate limiting considerations
  • Bun runtime for improved performance
  • ESM modules throughout
  • Vite build system
  • Type-safe operations
  • Data cleaning features including:
    • Issue mention extraction (ABC-123 format)
    • User mention extraction (@username format)
    • Markdown content cleaning
    • Content optimization for AI context
  • Self-assignment support with 'me' keyword and user ID caching
  • Advanced search capabilities with comprehensive filtering, logical operators, and relationship filters
  • Project management features including listing with filtering and pagination, and project update creation and retrieval

Error Handling

The server implements comprehensive error handling:

  • Network error detection with messaging
  • HTTP status code handling
  • Detailed error messages with status codes
  • Console error details logging
  • 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

License

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