# linear-mcp

> MCP Server

**Concise Descriptions:**

* **Model Context Protocol server for Linear. (38 chars)**
* **Linear MCP server: Provides model context data. (46 chars)**
* **Linear's Model Context Protocol (MCP) server.

## Overview

- **Category:** AI
- **Language:** TypeScript
- **Stars:** 30
- **Forks:** 9
- **Owner:** cosmix
- **GitHub:** https://github.com/cosmix/linear-mcp
- **Created:** 2025-01-24T09:43:11+00:00
- **Updated:** 2025-06-25T05:33:26+00:00
- **Source:** https://model-context-protocol.com/servers/linear-mcp

## Setup

## Setup

This section details how to install and configure the Linear MCP Server.

### Prerequisites

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

### 1. Clone the Repository

Clone the repository to your local machine:

```bash
git clone [repository-url]
cd linear-mcp
```

Replace `[repository-url]` with the actual URL of the repository.

### 2. Install Dependencies and Build

Install the necessary dependencies and build the project using Bun:

```bash
bun install
bun run build
```

### 3. Configure Environment Variables

The server requires a Linear API key.  Set the `LINEAR_API_KEY` environment variable.  It is recommended to set this globally for your system, or within your shell's configuration file (e.g., `.bashrc`, `.zshrc`).  Alternatively, you can set it directly in the configuration file in the next step, but this is less secure.

```bash
export LINEAR_API_KEY=your_api_key
```

Replace `your_api_key` with your actual Linear API token.

### 4. Configure the MCP Server

Edit the appropriate configuration file based on your operating system and the MCP client you are using:

**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: _(Currently not supported)_

Add the following configuration under the `mcpServers` object.  **Important:** Replace `/absolute/path/to/linear-mcp/build/index.js` with the *actual* absolute path to the `index.js` file in your `build` directory.

```json
{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/absolute/path/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "your_api_key"  //Consider removing this if LINEAR_API_KEY is set globally
      }
    }
  }
}
```

**Note:** If you have already set the `LINEAR_API_KEY` environment variable globally, you can omit the `env` section in the configuration file.  This is generally the preferred approach for security reasons.

### 5. Restart the MCP Server

Restart the MCP server within your client.

*   **Cline:** Restart the MCP server within Cline's MCP settings.
*   **Claude Desktop:** Restart Claude Desktop to load the new MCP server configuration.

## Tools

## Available Tools

This Linear MCP server provides the following tools for interacting with Linear's issue tracking system:

*   **`create_issue`**: Creates a new Linear issue or subissue.

    *   **Functionality:** Allows creating new issues within a specified team, optionally as a subissue of an existing issue. Supports setting the title, description, status, priority, assignee, and labels.
    *   **Input Schema:**
        ```json
        {
          "teamId": "string",
          "title": "string",
          "description": "string",
          "parentId": "string",
          "status": "string",
          "priority": "number",
          "assigneeId": "string | 'me'",
          "labelIds": ["string"]
        }
        ```
    *   **Example:**
        ```json
        {
          "teamId": "TEAM-123",
          "title": "Fix critical bug",
          "description": "Users are unable to login.",
          "status": "To Do",
          "priority": 1,
          "assigneeId": "me",
          "labelIds": ["bug", "urgent"]
        }
        ```

*   **`update_issue`**: Updates an existing Linear issue.

    *   **Functionality:** Modifies the fields of an existing issue, including title, description, status, priority, assignee, labels, and cycle.  The `status` field expects the status *name* (e.g., "In Progress"), not the ID. The `priority` field expects a number from 0 (None) to 4 (Low).
    *   **Input Schema:**
        ```json
        {
          "issueId": "string",
          "title": "string",
          "description": "string",
          "status": "string",
          "priority": "number",
          "assigneeId": "string | 'me'",
          "labelIds": ["string"],
          "cycleId": "string"
        }
        ```
    *   **Example:**
        ```json
        {
          "issueId": "ISSUE-456",
          "status": "In Progress",
          "priority": 2,
          "assigneeId": "USER-789"
        }
        ```

*   **`get_issue`**: Retrieves detailed information about a specific Linear issue.

    *   **Functionality:** Fetches issue details by ID, with the option to include related entities (e.g., comments, attachments).
    *   **Input Schema:**
        ```json
        {
          "issueId": "string",
          "includeRelationships": "boolean"
        }
        ```
    *   **Example:**
        ```json
        {
          "issueId": "ISSUE-123",
          "includeRelationships": true
        }
        ```

*   **`search_issues`**: Searches for Linear issues using a query string and advanced filters.

    *   **Functionality:** Enables searching for issues based on various criteria, including text queries, field-based filters, and logical operators. Leverages Linear's powerful filtering capabilities.
    *   **Input Schema:**
        ```json
        {
          "query": "string",
          "includeRelationships": "boolean",
          "filter": {
            "title": { "contains": "string", "eq": "string" },
            "description": { "contains": "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"
        }
        ```
    *   **Example:**
        ```json
        {
          "query": "performance",
          "filter": {
            "priority": { "gte": 2 },
            "status": { "eq": "In Progress" }
          }
        }
        ```

*   **`get_teams`**: Retrieves a list of Linear teams.

    *   **Functionality:** Returns a list of teams, optionally filtered by name.
    *   **Input Schema:**
        ```json
        {
          "nameFilter": "string"
        }
        ```
    *   **Example:**
        ```json
        {
          "nameFilter": "Frontend"
        }
        ```

*   **`delete_issue`**: Deletes an existing Linear issue.

    *   **Functionality:** Removes an issue from Linear.
    *   **Input Schema:**
        ```json
        {
          "issueId": "string"
        }
        ```
    *   **Example:**
        ```json
        {
          "issueId": "ISSUE-789"
        }
        ```

*   **`create_comment`**: Creates a new comment on a Linear issue.

    *   **Functionality:** Adds a comment to a specified issue. Supports markdown formatting in the comment body.
    *   **Input Schema:**
        ```json
        {
          "issueId": "string",
          "body": "string"
        }
        ```
    *   **Example:**
        ```json
        {
          "issueId": "ISSUE-123",
          "body": "This issue requires further investigation.  See [internal documentation](https://example.com)."
        }
        ```

*   **`get_projects`**: Retrieves a list of Linear projects.

    *   **Functionality:** Returns a list of projects, optionally filtered by name and supporting pagination.
    *   **Input Schema:**
        ```json
        {
          "nameFilter": "string",
          "includeArchived": "boolean",
          "first": "number",
          "after": "string"
        }
        ```
    *   **Example:**
        ```json
        {
          "nameFilter": "Website",
          "includeArchived": false,
          "first": 10
        }
        ```

*   **`get_project_updates`**: Retrieves project updates for a given project.

    *   **Functionality:** Fetches updates for a specific project, with filtering options for archived status, creation date, user, and health status.
    *   **Input Schema:**
        ```json
        {
          "projectId": "string",
          "includeArchived": "boolean",
          "first": "number",
          "after": "string",
          "createdAfter": "string",
          "createdBefore": "string",
          "userId": "string | 'me'",
          "health": "string"
        }
        ```
    *   **Example:**
        ```json
        {
          "projectId": "PROJECT-456",
          "createdAfter": "2024-01-01",
          "health": "onTrack"
        }
        ```

*   **`create_project_update`**: Creates a new update for a Linear project.

    *   **Functionality:** Adds a new update to a project, including a body, health status, and an option to hide the diff.
    *   **Input Schema:**
        ```json
        {
          "projectId": "string",
          "body": "string",
          "health": "onTrack | atRisk | offTrack",
          "isDiffHidden": "boolean"
        }
        ```
    *   **Example:**
        ```json
        {
          "projectId": "PROJECT-123",
          "body": "Progress is on track.  All major milestones have been completed.",
          "health": "on