Linear Issue Tracker MCP server

The MCP Linear App is a Model Context Protocol (MCP) integration that allows AI tools to interact with Linear. Through this integration, AIs can search, create, and update issues, add comments, and retrieve user and team information from Linear.

Prerequisites

• Node.js 18 or newer
• Linear API key

Getting a Linear API Key

Step-by-Step Instructions

1. Login to Linear

   • Visit Linear and log in to your account or create a new one

2. Navigate to Workspace Settings

   • Click your username in the top-left corner
   • Select "Workspace settings"

3. Find API Settings

   • In the left sidebar, scroll to find and click "API"

4. Generate a New API Key

   • Enter a descriptive label (e.g., "MCP Linear App")
   • Click "Create new API key"

5. Save Your API Key

   • Copy and store the key securely - it will only be shown once
   • Note that Linear has a rate limit of 1,500 requests per hour

Installation

Setting Up the MCP Linear App

1. Clone the repository:

   git clone [email protected]:zalab-inc/mcp-linear-app.git
   cd mcp-linear-app
   

2. Install dependencies:

   npm install
   

3. Create environment file: Create a .env file in the root directory with your Linear API key:

   LINEAR_API_KEY=your_linear_api_key_here
   

4. Build the project:

   npm run build
   

Configuration

Cursor Setup

1. Locate your Cursor MCP configuration file:

   • Windows: C:\Users\<username>\.cursor\mcp.json
   • macOS: ~/.cursor/mcp.json
   • Linux: ~/.cursor/mcp.json

2. Add Linear MCP server configuration:

   {
     "mcpServers": {
       "linear": {
         "command": "<path-to-node>",
         "args": [
           "<path-to-project>/dist/index.js"
         ],
         "env": {
           "LINEAR_API_KEY": "your_linear_api_key_here"
         }
       }
     }
   }
   

3. Example configuration:

   {
     "mcpServers": {
       "linear": {
         "command": "C:\\nvm4w\\nodejs\\node.exe",
         "args": [
           "H:\\mcp\\linear\\dist\\index.js"
         ],
         "env": {
           "LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxxxxxxxxxx"
         }
       }
     }
   }
   

4. Restart Cursor for changes to take effect

Claude Setup

1. Open Claude AI desktop app settings

2. Navigate to the "Developer" section

3. Find the "Tools" configuration section

4. Add Linear MCP configuration:

   {
     "tools": {
       "linear": {
         "command": "<path-to-node>",
         "args": [
           "<path-to-project>/dist/index.js"
         ],
         "env": {
           "LINEAR_API_KEY": "your_linear_api_key_here"
         }
       }
     }
   }
   

5. Example configuration:

   {
     "tools": {
       "linear": {
         "command": "/usr/local/bin/node",
         "args": [
           "/Users/username/projects/mcp-linear-app/dist/index.js"
         ],
         "env": {
           "LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxxxxxxxxxx"
         }
       }
     }
   }
   

Configuration for Other Platforms

The general approach for other AI platforms that support MCP:

1. Find the configuration area for external tools or MCP
2. Configure it to run Node.js with the dist/index.js file from this repository
3. Include your LINEAR_API_KEY in the environment configuration

Using the Linear Tools

Available Tools

After configuration, your AI will have access to these Linear tools:

• search_issues - Search for issues by keyword, status, or priority
• create_issue - Create a new issue
• get_issue - Get issue details
• update_issue - Update an existing issue
• create_comment - Add a comment to an issue
• get_comment - Get comments from an issue
• update_comment - Update or delete a comment
• get_profile - Get the current Linear user profile
• get_team_id - Get a list of teams and their IDs

Example Queries

In Cursor or Claude, you can prompt the AI to perform Linear-related tasks:

• Search for issues:

  Search for high priority issues in our Linear project.
  

• Create a new issue:

  Create a new issue in Linear with the title "Improve login page performance" and add it to the backlog.
  

• Get issue details:

  Get the details of the issue LIN-123 from Linear.
  

• Add comments:

  Add a comment to issue LIN-456 saying "This is fixed in the latest release. Please verify."
  

• Update issues:

  Update the priority of issue LIN-789 to urgent.
  

Example Workflow

Here's a typical workflow using these tools:

1. Find your team ID:

   What's my Linear team ID?
   

2. Create a new issue:

   Create a new Linear issue titled "Implement password reset feature" for the Engineering team with a high priority.
   

3. Search for issues:

   Find all high priority issues assigned to me that are currently in progress.
   

4. Update an issue:

   Update issue LIN-456 to add the description "This issue has been verified and tested on all browsers."
   

5. Add and retrieve comments:

   Add a comment to issue LIN-789 asking "Is this still a priority for this sprint?"
   

   Show me all the comments on issue LIN-321
   

Troubleshooting

If you experience issues:

• Verify your Linear API key is valid and has sufficient permissions
• Ensure Node.js is properly installed
• Check your MCP configuration in your AI platform
• Review log files for error messages

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":"<path-to-node>","args":["<path-to-project>/dist/index.js"],"env":{"LINEAR_API_KEY":"your_linear_api_key_here"}}'

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": "<path-to-node>",
            "args": [
                "<path-to-project>/dist/index.js"
            ],
            "env": {
                "LINEAR_API_KEY": "your_linear_api_key_here"
            }
        }
    }
}

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": "<path-to-node>",
            "args": [
                "<path-to-project>/dist/index.js"
            ],
            "env": {
                "LINEAR_API_KEY": "your_linear_api_key_here"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect