Linear MCP Server for Project Management Integration

Overview

The Linear MCP Server provides a small adapter layer that connects Linear (the issue and project tracking service) to systems that consume Model Context Protocol (MCP) tools. It exposes a set of HTTP endpoints and webhooks that let external tools, automation, and LLM-driven agents read, search, and update Linear issues and projects in a structured way. This makes it easier to integrate Linear into automated workflows, chatops, and AI assistants without coupling those consumers directly to Linear’s API.

Why this is useful: the MCP server standardizes access patterns (search, fetch, update, and webhook events) so consumers can treat Linear as a first-class “tool” in their orchestration. It handles authentication, rate considerations, and common mappings between Linear concepts (issues, labels, states) and tool-friendly representations, so developers can focus on automations and UX rather than API plumbing.

Features

• Exposes MCP-compatible HTTP endpoints for search, read, and mutate operations on Linear issues
• Receives and validates Linear webhooks and forwards them as structured MCP events
• Authentication and secrets management for Linear API keys and webhook verification
• Optional persistence or caching layer to reduce API calls
• Docker and local development support for fast setup
• Simple request/response shapes suitable for LLM toolchains and automation platforms
• Extensible: add custom mappings or additional endpoints to adapt to your workflow

Installation / Configuration

Prerequisites:

• Node.js 16+ (LTS recommended)
• A Linear API key with access to your workspace
• Optional: Docker if you prefer container deployment

Clone and install:

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

Create a .env file with required variables:

# .env
LINEAR_API_KEY=xxx_your_linear_api_key_xxx
WEBHOOK_SECRET=your_webhook_secret
MCP_PORT=8787
LOG_LEVEL=info
DATABASE_URL=sqlite://./data/dev.db   # optional

Start locally:

npm run build
npm start
# or for development
npm run dev

Run with Docker (example):

# docker-compose.yml
version: '3.8'
services:
  mcp-linear:
    image: ghcr.io/tacticlaunch/mcp-linear:latest
    ports:
      - "8787:8787"
    environment:
      - LINEAR_API_KEY=${LINEAR_API_KEY}
      - WEBHOOK_SECRET=${WEBHOOK_SECRET}
      - MCP_PORT=8787

Then:

docker-compose up -d

Test a health endpoint:

curl http://localhost:8787/health
# expected: {"status":"ok"}

Environment variables reference:

Available Tools / Resources

The server exposes a set of endpoints useful for integrations. Typical routes include:

• GET /tools/linear/search?q=… — search issues by text, filter by state/label
• GET /tools/linear/issues/:id — fetch issue details
• POST /tools/linear/update — update an issue (state, assignee, description)
• POST /webhooks/linear — receive and validate incoming Linear webhook events
• GET /health — basic healthcheck

Additional resources:

• OpenAPI/Swagger spec (if present in repo) to inspect request/response shapes
• Postman collection (optional) for manual testing
• Example scripts in /examples demonstrating common flows

Use Cases

1. Automated triage and assignment

   • Workflow: an LLM inspects a new issue via /tools/linear/search, classifies priority, and calls POST /tools/linear/update to assign a team and set the priority label.
   • Benefit: reduces manual triage time and enforces consistent labeling.

2. Real-time notifications in chatops

   • Workflow: the MCP server validates Linear webhooks and forwards structured events to a Slack bot or an LLM-driven assistant that summarizes the change and notifies stakeholders.
   • Benefit: teammates get concise, actionable updates without directly polling Linear.

3. Syncing external tasks into Linear

   • Workflow: a CI system or external ticketing tool queries available issues and creates linked Linear issues using the MCP server as a translation layer so IDs and states remain consistent.
   • Benefit: prevents duplicate work and keeps a single source of truth.

4. Context enrichment for LLMs

   • Workflow: an LLM-based assistant calls GET /tools/linear/issues/:id to fetch full issue context (title, comments, linked PRs) and uses that to generate release notes or draft responses.
   • Benefit: improves the quality of generated text by providing the model with structured project context.

Getting Help and Extending

• Inspect the repository for examples and tests to learn expected payloads
• Extend mappings by modifying the adapter layer that translates Linear GraphQL responses into MCP tool responses
• Add caching/persistence if you expect high read volume to stay within Linear rate limits

This MCP server is intended as a lightweight adapter — treat it as a starting point to integrate Linear into automation pipelines, LLM toolchains, and cross-tool synchronizations.