Linear MCP server

The Linear MCP Server enables access to Linear's issue tracking system through a standardized Model Context Protocol interface, allowing AI assistants to interact with your Linear workspace through tools like Claude Desktop or Cline.

Installation

Prerequisites

• Bun runtime (v1.0.0 or higher)
• Linear account with API access

Setup Steps

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 configuration file for your client:

   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

   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. For Claude Desktop, restart the application to load the new MCP server.

Using the MCP Tools

Creating Issues

Create a new Linear issue with the create_issue tool:

{
  "teamId": "TEAM123",     
  "title": "Fix login bug",      
  "description": "Users unable to login on Safari",
  "priority": 2,   
  "assigneeId": "me",
  "labelIds": ["label1", "label2"]
}

Updating Issues

Update an existing issue with the update_issue tool:

{
  "issueId": "ABC-123",    
  "title": "Updated title",      
  "status": "In Progress",     
  "priority": 1,   
  "assigneeId": "me"
}

Retrieving Issue Details

Get detailed information about a specific issue:

{
  "issueId": "ABC-123",
  "includeRelationships": true
}

Searching Issues

Search for issues using Linear's powerful filtering capabilities:

{
  "query": "login bug",
  "includeRelationships": true,
  "filter": {
    "assignedTo": "me",
    "state": { "type": { "eq": "started" } },
    "priority": { "gte": 2 }
  }
}

Working with Teams

Retrieve a list of Linear teams:

{
  "nameFilter": "Engineering"
}

Managing Comments

Add a comment to an issue:

{
  "issueId": "ABC-123",
  "body": "I've identified the root cause of this issue."
}

Deleting Issues

Delete an existing issue:

{
  "issueId": "ABC-123"
}

Working with Projects

Retrieve a list of projects:

{
  "nameFilter": "Q2 Roadmap",
  "includeArchived": false,
  "first": 10
}

Project Updates

Get project updates:

{
  "projectId": "PROJECT-123",
  "includeArchived": false,
  "first": 5,
  "health": "onTrack"
}

Create a new project update:

{
  "projectId": "PROJECT-123",
  "body": "Weekly update: completed 3 key features",
  "health": "onTrack"
}

Advanced Search Features

The search tool supports complex filtering with various comparators:

• String fields: eq, neq, in, nin, contains, startsWith, endsWith
• Number fields: eq, neq, lt, lte, gt, gte, in, nin
• Date fields: eq, neq, lt, lte, gt, gte (supports ISO 8601 durations)

Example of advanced search:

{
  "filter": {
    "and": [
      { "priority": { "gte": 2 } },
      { "createdAt": { "gt": "P2W" } },
      { "or": [
        { "title": { "contains": "login" } },
        { "description": { "contains": "authentication" } }
      ]}
    ],
    "assignedTo": "me",
    "labels": { "name": { "in": ["bug", "frontend"] } }
  }
}

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect