Linear MCP Server

What is Linear MCP Server about?

Enables AI assistants to read and manipulate Linear entities such as issues, projects, teams, users, roadmaps, documents, initiatives, and other core resources via MCP calls.

How to use Linear MCP Server?

Install
```
npx -y linear-mcp
```
(or clone the repo and run npm install)
Configure – create a .env file containing your Linear API key:
```
LINEAR_API_KEY=your_linear_api_key_here
```
Build the TypeScript source:
```
npm run build
```

Run the server:

STDIO mode (for CLI tools):

npm start   # or: node dist/index.js stdio

HTTP mode (SSE, remote access):

node dist/index.js http   # listens on PORT (default 3000)

Integrate with Claude Desktop or any MCP‑compatible client by pointing to the executable command or HTTP endpoint.

Key Features

Comprehensive Resource Access – issues, teams, projects, users, initiatives, roadmaps, milestones, documents, integrations, organization data.
Hierarchical Endpoints – e.g., linear://teams/{teamId}/issues, linear://projects/{projectId}/documents.
Toolset – create/update issues, add comments, manage projects, link/unlink initiatives, perform searches.
Prompt Templates – ready‑made prompts for bug reports, feature requests, project planning, status updates.
Multiple Transport Options – stdio for local MCP clients, HTTP with Server‑Sent Events for remote clients.
Configurable Logging & Port – LOG_LEVEL and SERVER_PORT environment variables.

Use Cases

AI‑assisted Issue Triage – an assistant can fetch open issues, suggest labels, and create new tickets based on user input.
Automated Project Planning – generate a project scaffold, assign issues, and link to initiatives programmatically.
Realtime Dashboard – a web UI consumes the HTTP SSE stream to display live updates of team boards.
Custom Search Bot – query across all Linear entities with natural‑language criteria.
Claude Desktop Integration – enhances Claude's capabilities with direct Linear actions.

FAQ

Q: Do I need a Linear API key? A: Yes, LINEAR_API_KEY is required and must have sufficient permissions for the actions you intend to perform.

Q: Which Node version is supported? A: Node.js 18 or later.

Q: Can I run the server behind a reverse proxy? A: Absolutely. The HTTP mode listens on a configurable port (default 3000) and works with any standard proxy.

Q: How do I change the logging level? A: Set the LOG_LEVEL environment variable (debug, info, warn, error).

Q: Is there a way to test the server locally? A: Use the MCP Inspector:

npx @modelcontextprotocol/inspector stdio -- npm start

A Model Context Protocol (MCP) server for Linear, providing AI assistants with access to Linear's project management capabilities.

Features

Resources: Access issues, projects, teams, users, roadmaps, documents, initiatives, and more
Tools: Create and update issues, manage projects, search, link projects to initiatives
Prompts: Templates for issue creation, bug reports, feature requests, and more

Setup

Prerequisites

Node.js 18 or later
A Linear API key

Installation

Clone the repository:

git clone https://github.com/yourusername/linear-mcp.git
cd linear-mcp

Install dependencies:
```
npm install
```
Create a .env file with your Linear API key:
```
LINEAR_API_KEY=your_linear_api_key_here
```
Build the project:
```
npm run build
```

Usage

Command-line (stdio)

To run the server with stdio transport (for use with CLI tools that support MCP):

npm start

Or:

node dist/index.js stdio

HTTP Server (for remote connections)

To run the server as an HTTP service with Server-Sent Events (SSE):

node dist/index.js http

This will start an HTTP server on port 3000 (configurable via PORT environment variable).

Development Mode

To run in development mode with automatic reloading:

npm run dev

Claude Desktop Integration

To use this server with Claude Desktop:

Build the project:
```
npm run build
```
In Claude Desktop, go to Settings → Advanced → MCP Configuration.

Add the following configuration (adjust paths to match your installation):

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

Save the configuration and restart Claude Desktop.

Alternatively, you can copy the provided claude-desktop-config.json file and modify the paths to match your installation.

Resources

The server provides access to all major Linear entities as resources:

Core Resources

Issues: linear://issues and linear://issues/{id}
Teams: linear://teams and linear://teams/{id}
Projects: linear://projects and linear://projects/{id}
Users: linear://users and linear://users/{id}
Initiatives: linear://initiatives and linear://initiatives/{id}

Additional Resources

Roadmaps: linear://roadmaps and linear://roadmaps/{id}
Milestones: linear://milestones and linear://milestones/{id}
Documents: linear://documents and linear://documents/{id}
Integrations: linear://integrations and linear://integrations/{id}
Organization: linear://organization

Specialized Resources

linear://teams/{teamId}/issues - Issues for a specific team
linear://users/{userId}/issues - Issues assigned to a specific user
linear://projects/{projectId}/issues - Issues in a specific project
linear://teams/{teamId}/states - Workflow states for a team
linear://teams/{teamId}/labels - Labels for a team
linear://teams/{teamId}/cycles - Cycles for a team
linear://teams/{teamId}/members - Members of a team
linear://teams/{teamId}/documents - Documents for a team
linear://projects/{projectId}/documents - Documents for a project
linear://projects/{projectId}/initiative - Initiative associated with a project
linear://initiatives/{initiativeId}/projects - Projects associated with an initiative
linear://milestones/{milestoneId}/projects - Projects for a milestone
linear://organization/subscription - Organization subscription details
linear://organization/auth-services - Organization authentication services
linear://integration-services - Available integration services

Tools

The server provides tools for:

Issue Management
- Creating new issues
- Updating existing issues
- Adding comments to issues
Project Management
- Creating new projects
- Updating existing projects
- Adding issues to projects
Initiative Management
- Creating initiatives
- Linking projects to initiatives
- Unlinking projects from initiatives
Search Capabilities
- Comprehensive search across Linear entities
- Finding issues with specific criteria

Prompts

The server provides prompt templates for:

Issue Related
- Creating new issues
- Creating bug reports
- Creating feature requests
Project Related
- Creating new projects
- Planning projects with issues
- Creating project status updates

Testing

Test with the MCP Inspector:

npx @modelcontextprotocol/inspector stdio -- npm start

Or, if running in HTTP mode, open the MCP Inspector in your browser and connect to your server's URL.

Environment Variables

LINEAR_API_KEY (required): Your Linear API key
SERVER_PORT (optional): Port for HTTP server (default: 3000)
LOG_LEVEL (optional): Logging level (default: info)

License

MIT

Linear MCP Server