# Linear MCP Server

[![CI](https://github.com/kamolc4/linear-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/kamolc4/linear-mcp-server/actions/workflows/ci.yml)
[![Verified by MCPForge](https://www.mcpforge.tech/api/badge/verified/linear-mcp-server)](https://www.mcpforge.tech/verified/linear-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```text
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](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

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

cd linear-mcp-server

# Install dependencies
npm ci
```

### 2. Configure environment

```bash
cp .env.example .env
```

Edit `.env`:

```bash
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

```bash
npm run dev
```

### 4. Check health

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

### 5. List MCP tools

```bash
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:

```bash
npm run build
npm start
```

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

```json
{
  "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:

```json
{
  "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](https://www.mcpforge.tech/verified/linear-mcp-server)

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:

- Linear MCP OAuth: https://www.mcpforge.tech/blog/linear-mcp-oauth
- Linear MCP Setup: https://www.mcpforge.tech/blog/linear-mcp-setup
- Linear MCP with Claude: https://www.mcpforge.tech/blog/linear-mcp-with-claude
- Linear MCP with Cursor: https://www.mcpforge.tech/blog/linear-mcp-with-cursor
- Linear MCP Security Review: https://www.mcpforge.tech/blog/linear-mcp-security-review
- Best MCP Servers for Claude Code: https://www.mcpforge.tech/blog/best-mcp-servers-for-claude-code

## 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

```bash
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](LICENSE).