linear-mcp

A small, read-only Model Context Protocol server for Linear. 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.

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):

{
  "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

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:

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.