Linear

For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.

Connect agents to Linear with the runnable example. It uses Node's built-in fetch and Linear's GraphQL API.

Start from the Linear MCP server template for setup instructions and a runnable workflow.

Configure access

Create a personal API key in Linear's Settings → Security & access, then configure:

LINEAR_API_KEY=your-personal-api-key
MCP_API_KEY=your-separate-client-secret

Clients send x-api-key on every request to the example's HTTP MCP endpoint. The server sends the Linear personal key in Authorization without a Bearer prefix. All clients share its workspace permissions, including issue creation. Use this example with trusted clients; team filters do not replace per-user authorization. For a multi-user application, implement an appropriate OAuth flow.

Available tools

Start with list-linear-teams({ limit: 10 }), then call list-linear-issues with a returned team UUID:

{
  "teamId": "your-team-uuid",
  "limit": 20
}

Both list tools return JSON in text content with nodes and pageInfo under teams or issues. They default to 20 results, accept 1–50, and never fetch additional pages automatically. When pageInfo.hasNextPage is true, pass pageInfo.endCursor as after, keeping other arguments unchanged. Archived issues are excluded by default.

Create an issue from a finding

An agent can inspect a page with the Firecrawl integration, review the findings, and then create a Linear issue when asked:

{
  "teamId": "your-team-uuid",
  "title": "Review pricing-page content",
  "description": "## Finding\nDescribe the finding and link to the source."
}

create-linear-issue is explicitly marked as a write that is not idempotent. It returns the created issue's ID, identifier, title, and URL. The example uses GraphQL variables for all input and leaves unspecified issue settings to Linear's defaults.

Errors and testing

Provider HTTP failures, GraphQL errors (even with HTTP 200 or partial data), and unsuccessful mutations return tool errors without raw provider error bodies. Requests time out after 30 seconds and are never retried automatically. If creation times out or returns an uncertain error, check Linear before retrying to avoid duplicate issues.

The README includes setup with Node 22 and pnpm, runnable discovery requests, and credential-free tests. All provider calls, including creation, are mocked in tests. HTTP smoke tests cover both MCP 2025-03-26 and 2026-07-28.