Skip to content
BranchesTags

Repository files navigation

Linear MCP Server

CI Verified by MCPForge License: MIT

A production-ready Model Context Protocol server for the Linear API.

This template lets Claude Desktop, Cursor, Windsurf, Claude Code, and other MCP-compatible clients list Linear issues, inspect issue details, create issues, list teams, and list projects through controlled Linear tools.

Built as a starter template for teams that want a secure baseline before adding company-specific issue tracking, engineering workflow, and project management automation.

Who this is for

This repository is useful for:

  • developers building AI assistants for Linear workspaces,
  • engineering teams connecting Linear to Claude, Cursor, or AI agents,
  • platform engineers who need a clean TypeScript MCP server example,
  • agencies building Linear automation for clients,
  • teams that want controlled Linear read/write tools with authentication and rate limiting.

Features

  • TypeScript + Express MCP server
  • Linear GraphQL API client
  • API key protection for /mcp
  • Rate limiting for MCP requests
  • Health endpoint at /health
  • Structured Pino logging
  • Zod-based environment validation
  • MCP tools for issues, teams, and projects
  • Jest + Supertest test setup
  • GitHub Actions CI workflow
  • Dockerfile and Docker Compose support

Architecture

Claude Desktop / Cursor / Windsurf
        │
        │  HTTP POST /mcp
        │  X-API-Key: <MCP_API_KEY>
        ▼
  Express Server
        │
        ├── JSON body parser
        ├── Rate limiter
        ├── API key middleware
        │
        ▼
   MCP SDK Handler
        │
        ├── list_issues    ─┐
        ├── get_issue      ─┤
        ├── create_issue   ─┤──► Linear GraphQL API
        ├── list_teams     ─┤
        └── list_projects  ─┘

  GET /health → Linear API dependency status

See the larger diagram in docs/architecture.md.

Source Code

The complete production-ready Linear MCP Server template is available on GitHub.

Repository:

https://github.com/kamolc4/linear-mcp-server

The repository includes:

  • Complete TypeScript source code
  • Linear GraphQL API client
  • MCP tools for issues, teams, and projects
  • GitHub Actions CI
  • Jest test suite
  • MIT License
  • Claude Desktop and Cursor configuration
  • Production deployment examples

Fork the repository or download it as a ZIP to start building immediately.

Available MCP tools

Tool Purpose
list_issues List Linear issues with optional filters for team, assignee, state, and priority.
get_issue Retrieve a Linear issue by ID or identifier such as ENG-123.
create_issue Create a new Linear issue in a selected team.
list_teams List Linear teams available to the configured API key.
list_projects List Linear projects, optionally filtered by team.

Quick start

1. Clone and install

# Clone repository
git clone https://github.com/kamolc4/linear-mcp-server.git

cd linear-mcp-server

# Install dependencies
npm ci

2. Configure environment

cp .env.example .env

Edit .env:

PORT=3000
NODE_ENV=development
LOG_LEVEL=info

LINEAR_API_KEY=lin_api_your_linear_api_key
LINEAR_API_URL=https://api.linear.app/graphql

MCP_API_KEY=replace-with-a-long-random-secret

RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=100

3. Run locally

npm run dev

4. Check health

curl http://localhost:3000/health \
  -H "X-API-Key: replace-with-your-mcp-api-key"

5. List MCP tools

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: replace-with-your-mcp-api-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Linear API setup

This starter template uses a Linear API key.

  1. Open Linear.
  2. Go to workspace settings.
  3. Open API settings.
  4. Create a personal API key or use a workspace token appropriate for your use case.
  5. Add it to .env as LINEAR_API_KEY.

For production, use a managed secret store and rotate API keys regularly.

If your Linear deployment uses OAuth or a brokered token service, replace the static LINEAR_API_KEY loading with per-user or per-workspace token resolution.

Connect to Claude Desktop

Build and start the server first:

npm run build
npm start

Then add an MCP server entry in your Claude Desktop configuration:

{
  "mcpServers": {
    "linear": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "X-API-Key": "replace-with-your-mcp-api-key"
      }
    }
  }
}

Restart Claude Desktop after editing the configuration.

Connect to Cursor

In Cursor, add a new MCP server using the HTTP endpoint:

{
  "name": "linear",
  "url": "http://localhost:3000/mcp",
  "headers": {
    "X-API-Key": "replace-with-your-mcp-api-key"
  }
}

Then restart Cursor or reload the MCP server list.

Security notes

This template is safer than a minimal demo, but you should harden it before production use.

Recommended production changes:

  • Store LINEAR_API_KEY and MCP_API_KEY in a managed secret manager, not in plain .env files.
  • Rotate MCP_API_KEY regularly.
  • Add per-user or per-workspace authorization if multiple users will access the server.
  • Restrict write tools such as create_issue behind approvals.
  • Add audit logs for every MCP tool call.
  • Use HTTPS in production.
  • Review Linear API permissions and keep scopes minimal.
  • Add monitoring for Linear API failures and rate limit responses.

Security Review

Verify this server with MCPForge:

https://www.mcpforge.tech/verify

MCPForge can help review:

  • exposed tools,
  • authentication behavior,
  • health checks,
  • compatibility with MCP clients,
  • risk level of write operations,
  • security posture before publishing or deployment.

Verified MCP profile:

https://www.mcpforge.tech/verified/linear-mcp

Starter template on MCPForge:

https://www.mcpforge.tech/code/linear-api-client-template

Read the complete Linear MCP Server guide:

https://www.mcpforge.tech/blog/linear-mcp-server

Related MCPForge guides:

Deployment

A common production setup:

  1. Deploy this service to Railway, Render, Fly.io, AWS, GCP, Azure, or a private Kubernetes cluster.
  2. Configure environment variables in the hosting provider.
  3. Set LINEAR_API_KEY and MCP_API_KEY as protected secrets.
  4. Verify /health before connecting production MCP clients.
  5. Test /mcp with tools/list.
  6. Run a public or private verification with MCPForge.

Local development commands

npm run lint
npm run typecheck
npm test
npm run build

API endpoints

Method Path Description
GET /health Health and Linear connectivity check.
POST /mcp MCP endpoint protected by X-API-Key.

Releases

Latest stable release:

v1.0.0

See the Releases page for the full changelog.

Contributing

Contributions are welcome.

If you want to improve this Linear MCP Server template, open an issue or submit a pull request.

Related MCP Server Templates

Looking for other production-ready MCP Server templates?

  • GitHub MCP Server
  • Slack MCP Server
  • Stripe MCP Server
  • Notion MCP Server
  • Shopify MCP Server
  • HubSpot MCP Server
  • PostgreSQL MCP Server

Browse the complete collection:

https://www.mcpforge.tech/code

License

MIT — see LICENSE.

About

Production-ready Linear MCP Server template for the Model Context Protocol (MCP). Build AI integrations with the Linear API using TypeScript, OAuth2, issues, projects, teams, comments, Claude Desktop, Cursor, Windsurf, and other MCP clients.

www.mcpforge.tech

Topics

aiai-agentsclaudeclaude-desktopcursorissue-trackinglinearlinear-apimcpmcp-servermcpforge-9f11a156model-context-protocoloauth2project-managementstarter-templatetypescriptwindsurf

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages