linear-mcp

# Linear MCP Server

A Model Context Protocol (MCP) server implementation that provides access to Linear's issue tracking system through a standardized interface. This server allows you to interact with Linear issues, projects, and updates using the MCP protocol, enabling integration with various AI-powered tools and workflows.

## Key Features

*   **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 the `'me'` keyword.
    *   Add comments to issues with Markdown support.
*   **Project Management:**
    *   Retrieve a list of Linear projects.
    *   Retrieve project updates.
    *   Create new project updates with health status.
*   **Advanced Search:** Leverage Linear's powerful filtering capabilities to search issues using custom queries with enhanced metadata.
*   **Cycle Filtering:** Filter issues by cycle (current, next, previous, or specific cycle by UUID or number).
*   **Relationship Tracking:** Maintain parent/child issue relationships with team inheritance.
*   **Type Safety:** Utilizes Linear's official SDK for type-safe operations.
*   **Error Handling:** Comprehensive error handling, including rate limit handling and input validation.
*   **Data Transformation:** Clean data transformation for optimal AI context.
*   **Label Management:** Label management and synchronization.

## Prerequisites

*   [Bun](https://bun.sh) runtime (v1.0.0 or higher)
*   Linear account with API access

## Environment Variables

The server requires a Linear API key to authenticate with the Linear API. Set the following environment variable:

```bash
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:

To use this MCP server with tools like Cline or Claude Desktop, you need to configure the tool to recognize and use the 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: (Not currently supported)

Add the following configuration under the mcpServers object. Replace /absolute/path/to/linear-mcp with the actual absolute path to your linear-mcp directory.

{
  "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 the development server:

bun run dev

Build the project:

bun run build

Available MCP Tools

This MCP server exposes the following tools for interacting with Linear. For detailed usage examples, refer to USAGE.md.

create_issue

Create a new Linear issue or subissue.

Input Schema:

{
  "teamId": "string",     // Required: The ID of the Linear team.
  "title": "string",      // Required: The title of the issue.
  "description": "string", // Optional: The description of the issue.
  "parentId": "string",   // Optional: The ID of the parent issue (for subissues).
  "status": "string",     // Optional: The status of the issue.
  "priority": "number",   // Optional: The priority of the issue (0-4).
  "assigneeId": "string | 'me'", // Optional: The ID of the assignee or 'me' for self-assignment.
  "labelIds": ["string"]  // Optional: An array of label IDs to apply to the issue.
}

update_issue

Update an existing Linear issue.

Input Schema:

{
  "issueId": "string",    // Required: The ID of the issue to update.
  "title": "string",      // Optional: The new title of the issue.
  "description": "string", // Optional: The new description of the issue.
  "status": "string",     // Optional: The new status NAME (e.g., "In Progress"). Must be valid for the issue's team.
  "priority": "number",   // Optional: The new priority (0-4).
  "assigneeId": "string | 'me'", // Optional: The new assignee ID or 'me' for self-assignment.
  "labelIds": ["string"], // Optional: An array of new label IDs.
  "cycleId": "string"     // Optional: The ID of the cycle to assign the issue to.
}

get_issue

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

Input Schema:

{
  "issueId": "string",              // Required: The ID of the issue to retrieve.
  "includeRelationships": "boolean"  // Optional: Whether to include related issues (e.g., parent, children). Defaults to false.
}

search_issues

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

Input Schema:

{
  "query": "string",                   // Optional: A free-text search query.
  "includeRelationships": "boolean",   // Optional: Whether to include related issues. Defaults to false.
  "filter": {                         // Optional: Advanced filtering options.
    "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'",   // Optional: Filter by assignee ID or 'me' for self-assigned.
    "createdBy": "string | 'me'"     // Optional: Filter by creator ID or 'me' for self-created.
  },
  "projectId": "string",                // Optional: Filter by project ID.
  "projectName": "string"               // Optional: Filter by project name.
}

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