mcp-linear

Linear MCP Server

A Node.js implementation of an MCP server for Linear integration.

About

This MCP (Model Context Protocol) server provides a standardized interface for AI models to interact with Linear issue tracking functionality.

Key Features

• Standard MCP protocol implementation for Linear using the official MCP SDK
• Support for searching issues, reading details, updating, and commenting

Getting Started

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.

Using with MCP Inspector

The server runs in stdio mode, which means you can connect to it with the 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

Usage 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"
        }
      }
    ]
  }
}

Usage 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

Project Structure

/
├── src/                     # Source code
│   ├── effects/             # Effects implementation
│   │   ├── linear/          # Linear API effects
│   │   │   └── types/       # Linear type definitions
│   │   └── logging/         # Logging effects for safe logging with STDIO
│   ├── tools/               # MCP tools implementation
│   │   ├── types/           # Tool type definitions
│   │   └── utils/           # Tool utility functions
│   ├── utils/               # Utility modules
│   │   └── config/          # Configuration utilities
│   └── index.js             # Main entry point
├── docs/                    # Documentation
│   └── llm_context/         # Documentation for LLMs
├── logs/                    # Log files (created at runtime)
└── package.json             # Project configuration

Available Tools

The MCP server exposes the following tools:

• list_issues - List Linear issues (also called tickets) 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, the following tool aliases are also available:

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

Troubleshooting

If you're having issues with the Linear MCP server:

1. Check your Linear API key: Make sure 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: Make sure your Linear API key has appropriate permissions and that you can access the Linear API directly.

Architecture

The application follows an effects-based architecture:

• Effects: Side-effecting operations are isolated in the effects directory:

  • linear: Provides access to Linear API using the official Linear SDK
  • logging: Safe logging that doesn't interfere with STDIO transport

• Tools: MCP tool implementations that use effects for side-effects:

  • Each tool follows a consistent pattern with input validation using Zod
  • Tools are exposed through the MCP protocol via the server
  • Each tool can access the Linear client through the linear effect

• Utils: Utility modules for configuration and common functionality

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.