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

Clone the repository
Install dependencies

npm install

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.

Start the server in one terminal:

npm start

Visit the web-based inspector at: https://inspector.modelcontextprotocol.ai
Select "stdio" as the transport type
Enter the following command:

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

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:

Configure the MCP server in your Claude Desktop or Cursor settings
Restart your application
Ask: "Search for Linear issues containing 'bug'"
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:

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".

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
}

Check log files: Examine logs in the logs/mcp-linear.log file for detailed error information.
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.

Linear Integration