Overview

This project implements a Model Context Protocol (MCP) server that exposes Linear (linear.app) as a structured, queryable model context. It gives AI assistants and other MCP-capable clients programmatic access to Linear entities — issues, projects, initiatives, teams, users, roadmaps, documents, and related workflows — using the official Linear SDK under the hood. The server maps Linear resources to MCP resource URIs and provides tools for creating, updating, searching, and linking entities.

For developers building assistant integrations, the Linear MCP server simplifies automations like creating issues from natural language, querying team backlogs, linking projects to initiatives, and generating status summaries. It supports both local stdio transports for CLI integrations and an HTTP/SSE transport for remote MCP clients, plus templates/prompts for common issue and project workflows.

Features

Full access to core Linear entities: issues, projects, teams, users, initiatives, roadmaps, milestones, documents
CRUD operations for issues and projects; linking/unlinking projects and initiatives
Search across Linear entities with flexible filters
Team-scoped resources: states, labels, cycles, members, documents
HTTP (SSE) and stdio transports for MCP clients
Prompt templates for issue creation, bug reports, and feature requests
Integration-ready: environment-driven config and ready-to-drop-in Claude Desktop example
Built with TypeScript and the official Linear SDK

Installation / Configuration

Prerequisites:

Node.js 18+
A Linear API key

Clone and install:

git clone https://github.com/anoncam/linear-mcp.git
cd linear-mcp
npm install

Configure environment variables in a .env file:

# .env
LINEAR_API_KEY=your_linear_api_key_here
SERVER_PORT=3000          # optional, default 3000
LOG_LEVEL=info            # optional

Build and run:

npm run build
# stdio transport (for local MCP clients)
node dist/index.js stdio

# http transport (SSE) — default port 3000 or use SERVER_PORT
node dist/index.js http

Development mode with auto-reload:

npm run dev

Claude Desktop MCP configuration example (adjust paths and env):

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

Repository: https://github.com/anoncam/linear-mcp

Available Resources

The server maps Linear entities to MCP resource URIs. Common endpoints:

Resource URI pattern	Description
linear://issues	All issues
linear://issues/{id}	Specific issue
linear://projects	All projects
linear://projects/{id}	Specific project
linear://teams	All teams
linear://teams/{id}	Specific team
linear://initiatives	All initiatives
linear://initiatives/{id}	Specific initiative
linear://teams/{teamId}/states	Workflow states for a team
linear://projects/{projectId}/initiative	Initiative associated with a project
linear://users/{userId}/issues	Issues assigned to a user
linear://organization	Organization metadata and subscription

Specialized resource collections allow filtered access (team issues, project documents, initiative projects, milestone projects, etc.).

Available Tools

The MCP server exposes tools (actions) that clients can invoke:

Issue Management
- createIssue(title, description, projectId?, assigneeId?, labels?)
- updateIssue(issueId, fields)
- addComment(issueId, body)
Project Management
- createProject(name, teamId?, description?)
- updateProject(projectId, fields)
- addIssueToProject(issueId, projectId)
Initiative Management
- createInitiative(name, description?)
- linkProjectToInitiative(projectId, initiativeId)
- unlinkProjectFromInitiative(projectId)
Search
- searchIssues(query, filters)
- searchProjects(query, filters)

Each tool returns structured responses and raises MCP-style errors for authorization or validation problems.

Use Cases

Create an issue from chat: A user describes a bug in a chat; the assistant calls createIssue with extracted title/description and assigns it to the relevant team/project.
Triage backlog: Ask the assistant for all high-priority issues in Team A; it queries linear://teams/{teamId}/issues, filters by state/labels, and returns summaries.
Link project to initiative: During planning, create a project and immediately link it to an existing initiative using linkProjectToInitiative.
Generate status updates: Query project issues and initiative progress to build a concise status report for stakeholders.
Automated labeling and workflow transitions: Bulk-update issues matching a search (e.g., assign label “needs-investigation” and move to triage state).

Testing and Debugging

Use the MCP Inspector locally:

npx @modelcontextprotocol/inspector stdio -- npm start
# or connect via HTTP to: http://localhost:3000 (SSE endpoints)

Set LOG_LEVEL to debug for detailed logs. Handle Linear API rate limits and permission errors by verifying the API key scope and using sensible caching.

License: MIT

Linear MCP Server for Projects, Initiatives, Issues, Teams