# linear-mcp

A small, read-only [Model Context Protocol](https://modelcontextprotocol.io/)
server for [Linear](https://linear.app/). Bring your own Linear API key.

Written because none of the existing community Linear MCP servers were
maintainers I wanted to trust with a personal API key, and because the surface
I actually needed (list issues in a cycle, get an issue, search) is small
enough to own outright.

## What it exposes

Five read-only tools:

| Tool | Purpose |
|---|---|
| `list_teams` | Enumerate teams in the workspace (key, name, UUID). |
| `list_cycles` | List cycles for a team, filterable by past / current / future. |
| `list_issues_in_cycle` | Issues in a specific cycle. Accepts `cycle_id` or `(team, cycle_number)`. |
| `get_issue` | Full details for one issue, including description, labels, and recent comments. |
| `search_issues` | Text search across the workspace's issues, optionally scoped to a team. |

No mutation tools — this server can't create, edit, or delete anything in
Linear. That's a deliberate choice; adding write tools is a separate PR.

## Install

Requires **Node 20 or later**.

```sh
git clone https://github.com/puneetsharma2791/linear-mcp.git
cd linear-mcp
npm install
npm run build
```

That produces `dist/index.js`, which is the executable the MCP host will run.

## Get a Linear API key

1. Open <https://linear.app/settings/api>.
2. Click **Create key**, name it something like "MCP - laptop".
3. Copy the key — it starts with `lin_api_`. You won't see it again.

The key inherits your Linear permissions, so this server will see whatever
you can see in the Linear app.

## Wire into Claude Code

Edit your MCP client config (for Claude Code, typically
`~/.config/claude/claude_desktop_config.json` or the equivalent per OS; for
Claude Code CLI check `claude --help`):

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

Restart the client. Tools will appear as `linear__list_teams`,
`linear__get_issue`, etc.

### Other MCP clients

Any MCP client that speaks stdio works. Point its "server command" at
`node /absolute/path/to/linear-mcp/dist/index.js` and pass `LINEAR_API_KEY`
in the environment.

## Development

```sh
cp .env.example .env      # then paste your API key
npm install
npm run dev               # tsc --watch — rebuilds on edit
```

Smoke-test the built server by piping an MCP handshake in on stdin:

```sh
LINEAR_API_KEY=lin_api_... node dist/index.js < /dev/null &
# The server will exit cleanly on stdin close. To exercise a tool call,
# see the MCP inspector: https://github.com/modelcontextprotocol/inspector
```

## Adding a new tool

Each tool is one file under `src/tools/` with three exports:

- a **schema** (`{name, description, inputSchema}`) — declared to the MCP client
- a **zod parser** — validates arguments at call time
- an **async handler** — runs the query and returns a plain object

Then add one entry each to `ListToolsRequestSchema` and the `dispatch`
switch in `src/index.ts`. That's the whole flow.

## License

MIT. See [LICENSE](./LICENSE).