Linear MCP server

The Linear MCP server provides a standardized interface for AI models to interact with Linear issue tracking functionality, following the Model Context Protocol. It enables searching issues, reading details, updating, and commenting through a standard API.

Prerequisites

• Node.js (v18 or later)
• Linear API key

Installation

1. Clone the repository
2. Install dependencies

npm install

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

LINEAR_API_KEY=your_linear_api_key_here

Running the Server

Start the server:

npm start

For development with file watching:

just dev

For development with debug logging:

just debug

Or set environment variables manually:

LOG_LEVEL=DEBUG NODE_ENV=development node src/index.js

Logs will be written to the logs/mcp-linear.log file to avoid interfering with the STDIO transport.

Integration with MCP Tools

Using with MCP Inspector

1. Start the server in one terminal:

npm start

2. Visit the web-based inspector at: https://inspector.modelcontextprotocol.ai

3. Select "stdio" as the transport type

4. Enter the following command:

node /path/to/mcp-linear/src/index.js

5. Click "Connect" to connect to your running server

Integration with Claude Desktop

Add the following to your Claude Desktop configuration file (typically at ~/.config/Claude Desktop/claude_desktop_config.json):

{
  "mcp": {
    "servers": [
      {
        "name": "Linear",
        "command": "node /path/to/mcp-linear/src/index.js",
        "env": {
          "LINEAR_API_KEY": "your_linear_api_key_here"
        }
      }
    ]
  }
}

Integration with Cursor

For Cursor, add the following to your settings:

{
  "ai.mcp.servers": [
    {
      "name": "Linear",
      "command": "node /path/to/mcp-linear/src/index.js",
      "env": {
        "LINEAR_API_KEY": "your_linear_api_key_here"
      }
    }
  ]
}

Testing Your Integration

To verify your setup:

1. Configure the MCP server in your Claude Desktop or Cursor settings
2. Restart your application
3. Ask: "Search for Linear issues containing 'bug'"
4. The assistant should detect and use the Linear MCP server to retrieve results

Available Tools

The Linear MCP server provides the following tools:

• list_issues - List Linear issues with various filtering options (assignee, status, etc.)
• get_issue - Get detailed information about a specific Linear issue by ID
• list_members - List Linear team members with optional filtering by name
• list_projects - List Linear projects with optional filtering by team, name, and archive status
• get_project - Get detailed information about a specific Linear project including issues, members and more
• list_teams - List Linear teams with details about their members, projects, and issues
• add_comment - Add a comment to a specific Linear issue
• create_issue - Create a new issue in Linear with customizable title, description, priority, and assignee

For backward compatibility, these aliases are also available:

• list_tickets - Alias for list_issues
• get_ticket - Alias for get_issue

Troubleshooting

If you encounter issues with the Linear MCP server:

1. Check your Linear API key: Ensure you've set a valid Linear API key in your .env file or environment variables. Linear API keys should start with "linapi".

2. Enable debug logging:

   a. When starting the MCP server:

   just debug
   # or
   LOG_LEVEL=DEBUG NODE_ENV=development node src/index.js
   

   b. In your client configuration (Claude Desktop, Cursor, etc.):

   "env": {
     "LINEAR_API_KEY": "your_linear_api_key_here",
     "LOG_LEVEL": "DEBUG"
   }
   

   c. When calling tools directly, add the debug parameter:

   {
     "debug": true
   }
   

3. Check log files: Examine logs in the logs/mcp-linear.log file for detailed error information.

4. Verify Linear API access: Ensure your Linear API key has appropriate permissions and that you can access the Linear API directly.

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

3. Restart Claude Desktop for the changes to take effect