Linear MCP Server Cursor IDE Setup 2026

How do you set up the Linear MCP server in Cursor? Add a linear entry under mcpServers in ~/.cursor/mcp.json. For most people that is Linear's hosted remote URL (https://api.linear.app/mcp/) plus a Linear API key in an Authorization: Bearer header. The other official path is a local Docker process from ghcr.io/linear/linear-mcp-server. Restart Cursor, confirm a green status on the server, then ask for something that requires a live Linear call, such as listing your issues or teams.

This page owns linear mcp server cursor ide setup 2026. It is the Cursor-specific setup for the official Linear server: the mcp.json blocks Linear publishes for Cursor, API key versus local OAuth, toolsets, read-only mode, and the errors that actually show up in Cursor logs.

This is not a GitHub, GitLab, Jira, or Bitbucket guide — those have their own articles linked at the bottom. If you need GitHub repos/PRs instead of Linear issues, see GitHub MCP Cursor setup.

Use the official Linear MCP server

The maintained server is Linear's own linear/linear-mcp-server. Linear documents two supported ways to run it: the hosted remote URL https://api.linear.app/mcp/, and the official Docker image ghcr.io/linear/linear-mcp-server.

Why older Linear MCP tutorials fail in Cursor

Three published facts matter more than leftover 2025 screenshots.

The supported distribution changed. Community posts and older site copy still tell Cursor to start the retired community package over stdio. Linear's Cursor install page says that package stopped working in April 2025. The replacement is the hosted URL or the official ghcr.io image.

Cursor's schema is not VS Code's schema. Cursor's MCP reference uses a top-level mcpServers object. Linear's Visual Studio, JetBrains, and Xcode snippets often use servers, sometimes with type http and a requestInit headers wrapper. Pasting a VS Code or Visual Studio fragment into the Cursor config file is a common reason the server never appears.

Linear states the MCP server is available to all Linear workspace members. Individual tools still inherit the access rules of the matching Linear feature. A tool that talks to Linear's API still needs appropriate workspace permissions. The server does not grant extra issue access beyond the signed-in account or the API key you attach.

Remote auth on Cursor is not the same as remote auth on Copilot Chat in Visual Studio. Linear's docs for Visual Studio, JetBrains, Xcode, and Eclipse show a remote URL with one-click OAuth and no API key. Linear's Cursor install guide says the opposite for this host: while Cursor supports OAuth for some MCP servers, the Linear server currently requires an API key on the remote path. This article follows the Cursor-specific page.

Prerequisites

From Linear's Cursor install guide and Cursor's MCP docs:

You do not register an OAuth app for the remote Cursor flow Linear documents. You do not need Node.js for either official path. You do not need Linear's native Copilot integration inside Cursor to use this MCP server; Cursor's own agent talks to MCP tools. Linear policy notes on Linear's pages apply when you are using Linear as the host, not when Cursor is the host.

Step 1: Create a Linear API Key

The remote Cursor path Linear publishes authenticates with an API key. The local Docker path can use an API key as well. An API key acts with the authority of the account that created it, then is further limited by the scopes or permissions on that key. It cannot grant access the account does not already have.

Linear currently supports API keys tied to your workspace member account.

Linear API key (recommended by Linear):

1. Linear → Settings → API → Create new API key.
2. Set a name and an optional expiration. Linear allows non-expiring keys, but a workspace policy can restrict that.
3. Choose the workspace and the scopes your assistant actually needs. Linear documents that API keys are limited to the workspace they are created in.
4. Limit access to the teams and projects the assistant actually needs. API keys always include read-only access to all public teams and projects.
5. Under Permissions, grant only the API scopes that match the Linear features you will call. Linear's API docs state the permission each endpoint needs. This page does not invent a required-permission matrix for every MCP tool.
6. Generate the key. If the workspace requires approval, the key stays pending and can only read public resources until an admin approves it.

Treat the key like a password. Do not paste a live key into this article, into a committed file, or into chat. In examples below, the placeholder is YOUR_LINEAR_API_KEY or an environment variable name.

Step 2: Choose the remote endpoint or local Docker

Linear's Cursor install guide presents remote as recommended. Nothing to pull, nothing to keep running. The hosted server is also where Linear adds remote-only toolsets such as copilot (Linear's cloud agent) and linear_support_docs_search.

Run the local Docker server when you want the process on your machine, when you want local OAuth instead of putting an API key in Cursor's config, or when you are on Linear Enterprise. Linear's enterprise page states Linear Enterprise does not host the remote MCP server. Enterprise users must use the local server and set LINEAR_HOST.

There is no third official path. The trade-off in general terms is covered in Local vs Remote MCP Servers. Container mechanics that are not Linear-specific are in Docker MCP Server Setup.

Step 3a: Remote endpoint config (Cursor)

Cursor reads MCP config from two files and merges them. Project-level wins if the same server name appears in both.

Linear's Cursor install guide shows a Streamable HTTP block. The top-level key is mcpServers. That is Cursor's schema. The url is https://api.linear.app/mcp/ and the Authorization header uses the Bearer scheme plus your key placeholder YOUR_LINEAR_API_KEY.

Replace the placeholder with the key from step 1. Do not commit a live key.

Cursor also documents config interpolation. If you already export the key in your environment, keep the secret out of the JSON file by writing Bearer ${env:LINEAR_API_KEY} as the header value. Cursor resolves ${env:NAME} in url and headers. Restart Cursor after changing the shell profile that defines the variable. Remote HTTP servers do not support Cursor's envFile key; that option is stdio-only.

Linear's Cursor page also offers a one-click install control that writes the same remote config, then tells you to open Tools and Integrations, MCP tools, click the pencil next to linear, and replace YOUR_LINEAR_API_KEY. Cursor's own help describes the marketplace path as Customize, then MCPs, then Add to Cursor, then complete any auth prompts.

Save the file. Restart Cursor.

Remote mcp.json from Linear's Cursor install guide, wrapped in Cursor's mcpServers key:

{
  "mcpServers": {
    "linear": {
      "url": "https://api.linear.app/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_LINEAR_API_KEY"
      }
    }
  }
}

Interpolated form using Cursor's documented ${env:NAME} syntax:

{
  "mcpServers": {
    "linear": {
      "url": "https://api.linear.app/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:LINEAR_API_KEY}"
      }
    }
  }
}

Step 3b: Local Docker with an API Key

The local server is the official image. Docker Desktop must already be running. Linear's Cursor install guide says an API key takes precedence over OAuth.

The command is docker. The args are run, -i, --rm, -e, LINEAR_API_KEY, then the image ghcr.io/linear/linear-mcp-server. The env block sets LINEAR_API_KEY to YOUR_LINEAR_API_KEY or to ${env:LINEAR_API_KEY}.

The -e LINEAR_API_KEY argument without a value tells Docker to pass that variable from the process environment into the container. Cursor's env block is what supplies the value to that process.

Do not add a tag this page did not read from the official snippet. The published image name is ghcr.io/linear/linear-mcp-server.

Step 3c: Local Docker with OAuth (no API Key)

On linear.app, the official image ships with a registered Linear OAuth app baked in. Linear's Cursor install guide and the local OAuth doc say you provide no client ID: the server opens a browser login on first use and keeps the token in memory only. In Docker you must publish a fixed callback port to loopback. Linear's documented port for the official app is 8085.

Publish to 127.0.0.1 only. Linear's OAuth doc warns that a plain publish of 8085 to all interfaces would expose the authorization code on your network because the callback inside the container listens on all interfaces. A busy 8085 is fatal on purpose: the server stops rather than falling back silently.

If LINEAR_API_KEY is set, the server uses the API key and skips OAuth. For Linear Enterprise or custom hosts, the baked-in app is not used. Those hosts need your own OAuth or Linear App plus the client id flag or LINEAR_OAUTH_CLIENT_ID, which Linear documents in the local OAuth login page of the official repo. This page does not invent a client ID.

Headless or unpublished-port containers fall back to Linear's device-code flow. That is an official fallback, not a third install method.

Local Docker API key block from Linear's Cursor install guide:

{
  "mcpServers": {
    "linear": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "LINEAR_API_KEY",
        "ghcr.io/linear/linear-mcp-server"
      ],
      "env": {
        "LINEAR_API_KEY": "YOUR_LINEAR_API_KEY"
      }
    }
  }
}

Local Docker OAuth block from the same guide. Port 8085 is bound to loopback only:

{
  "mcpServers": {
    "linear": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "127.0.0.1:8085:8085",
        "-e",
        "LINEAR_OAUTH_CALLBACK_PORT",
        "ghcr.io/linear/linear-mcp-server"
      ],
      "env": {
        "LINEAR_OAUTH_CALLBACK_PORT": "8085"
      }
    }
  }
}

Step 4: Restart Cursor and verify

Linear's Cursor install guide:

1. Restart Cursor completely.
2. Check for a green dot in Settings, then Tools and Integrations, then MCP Tools.
3. In chat or Composer, open Available Tools and confirm Linear tools are listed.
4. Test with: List my Linear issues.

Cursor asks for approval before MCP tools run, unless you changed the approval mode. Cursor's help says that in Cursor 3.6 and above, default Auto-review under Settings, Agents, Approvals and Execution lets allowlisted MCP tools run immediately and routes the rest through a classifier. Allowlist keeps the older allowlist-only behavior. See Cursor IDE MCP Agent Mode.

If the server is listed but chat never calls a tool, open logs. Cursor's MCP FAQ: Output panel, Command-Shift-U on macOS or Control-Shift-U on Windows and Linux, then MCP Logs. Toggle the server off and on from Customize if it connected before auth finished.

Global vs project config

Use ~/.cursor/mcp.json for a Linear connection you want in every workspace. Use .cursor/mcp.json in a project root when that repo needs a differently scoped key, a read-only URL, or a different toolset list.

Cursor's help says a project file can be committed so teammates get the same tools. That is safe only when the file contains no secret. An API key in headers or env is a secret. Interpolate from the environment, or keep the key in the global file that is not in git. Add .cursor/mcp.json to .gitignore if it holds a key.

The key name linear is only a label in Cursor's MCP panel. The url or command is what connects.

Controlling which tools Cursor sees

The server groups tools into toolsets. Linear's docs say enabling only the toolsets you need improves tool-selection accuracy and frees context. Turning on all is tempting and usually a mistake.

Default set. Linear's Configuring toolsets page says the default toolsets enabled automatically are issues, projects, and teams. The repo server-configuration.md says that if you specify no configuration, the default toolsets are issues, projects, teams, users. This page does not pick a winner. Treat the live README as source of truth when those two pages disagree.

Remote URL paths, from Linear's remote-server.md. The toolset segment is a single name, not a comma-separated list:

To combine several toolsets on one entry, use headers, not a comma in the path.

Remote headers and their local equivalents:

On the local server those controls are environment variables or flags. Environment variables take precedence over flags. In Cursor's Docker block, put the matching LINEAR_* names in args as -e VAR and set the values in env.

Special keywords Linear documents: all enables every available toolset; default includes the standard set alongside others. Linear's example is default,cycles.

Toolsets published on the remote-server page: cycles, issues, labels, projects, teams, users, plus the keywords default and all.

Remote-only toolsets on that same page: copilot and linear_support_docs_search. Linear's configure-toolsets page also names copilot and linear_support_docs_search as remote-only. copilot tools that invoke Linear's cloud agent require a paid Linear subscription.

This page does not publish a full individual-tool inventory. Linear points at the Tools section of the README for the complete list. Official configuration examples name tools such as get_issue, list_issues, create_issue, update_issue, and archive_issue. Treat the live README as source of truth if a name moves.

Cursor's documentation does not publish a maximum number of MCP tools. Keep the list short as a reliability practice, not as a workaround for a documented cap.

Read-only remote example with interpolated key:

{
  "mcpServers": {
    "linear": {
      "url": "https://api.linear.app/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:LINEAR_API_KEY}",
        "X-MCP-Toolsets": "issues,projects,teams",
        "X-MCP-Readonly": "true"
      }
    }
  }
}

Same idea as a path: https://api.linear.app/mcp/x/all/readonly

Read-only mode

If you want the assistant browsing issues, projects, and cycles with no path to writes, turn on read-only. Linear's server-configuration guide says this mode disables all tools that are not read-only even if they were requested. create_issue stays unregistered even when the issues toolset is on.

Remote: append /readonly to any of the URLs above, or send X-MCP-Readonly. Local: LINEAR_READ_ONLY or --read-only.

Pair read-only with a key that only has read permissions so the limit is enforced on both sides. Linear's API docs say to choose the minimal permissions that meet your needs. That arrangement is the default worth using on any workspace you do not want an agent pushing to. Broader credential patterns: How to Authenticate MCP Servers and MCP Security Best Practices.

Lockdown mode is separate. Linear describes it as a best-effort content filter for public workspaces: the server surfaces content from users with edit access, and as an exception from linear-bot and copilot. Private workspaces are unaffected. It does not restrict what the credential can otherwise read or write. Do not treat it as a replacement for a read-scoped key.

Prompts that match documented tools

These are examples, not guaranteed outputs. Use a real team, project, issue ID, and cycle from accounts the key can see.

Cursor will prompt you to approve write tools. Approve get_issue or list_issues freely. Pause on create_issue, update_issue, and archive_issue until you have read the arguments.

Running Linear MCP alongside GitHub MCP in the same mcp.json

A common pairing is Linear for issue tracking and GitHub for the actual code, both wired into the same Cursor agent so it can move between "what does this PR change" and "which Linear issue does it close" without you switching context. There is no combined Linear+GitHub MCP server — the two servers are independent and authenticate separately — but they live fine as two entries under the same mcpServers key:

{
  "mcpServers": {
    "linear": {
      "url": "https://api.linear.app/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:LINEAR_API_KEY}"
      }
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:GITHUB_MCP_PAT}"
      }
    }
  }
}

With both green under Settings, Tools and Integrations, MCP Tools, a single prompt can cross both systems: "Read PR #212 on this repo, then find the Linear issue it's linked to and check whether the PR actually closes everything in the issue's acceptance criteria." Cursor resolves that into a get_pull_request call against GitHub and a get_issue or list_issues call against Linear, then reasons over both results together. This is the setup most people typing "linear mcp server cursor ide setup" alongside a GitHub question are actually after — not a single unified server, just both configured together so the agent has both contexts at once. The GitHub MCP Server Cursor IDE Setup guide covers GitHub-specific toolsets, PAT scoping, and the same pairing from the GitHub side.

Linear Enterprise

Official enterprise rules, translated into Cursor's mcpServers schema:

Pass LINEAR_HOST the same way you pass the key: -e LINEAR_HOST in args, value in env. Do not point a linear.app remote block at an Enterprise host and hope it works.

Matching toolset configuration to your actual workflow

Enabling every toolset is the default, but it isn't always the right default. A backend team doing issue triage rarely needs the cycles or copilot toolsets in its tool list; a narrower X-MCP-Tools: issues,projects cuts down how many tool descriptions Cursor's agent has to weigh before picking one, which matters more as the tool list grows across every MCP server you have connected, not just Linear. Cursor's MCP Logs panel shows which tools a server actually registered after connecting — use that to check what a given toolset selection produced rather than assuming from the name alone.

API key hygiene is the same as any other long-lived credential: store it in your shell environment or a secrets manager, not committed inside mcp.json, and use ${env:LINEAR_API_KEY} interpolation in a project-level config so the literal value never lands in a file that might get checked into version control. Linear's API key management page is the source of truth for viewing, scoping, and revoking a specific key if one is ever exposed — this guide won't invent a specific rotation cadence Linear doesn't publish.

Defense-in-depth is worth applying deliberately rather than as an afterthought: pair /readonly or X-MCP-Readonly with an API key that only has read scopes to begin with, so a leaked key or a misfired write prompt can't modify issues even if read-only mode were somehow bypassed at the client level. See the read-only mode section below for the exact header and env var names.

Multi-workspace and multi-environment configs

Teams running more than one Linear workspace — a production org and a sandbox, or separate workspaces per client — can maintain isolated configs with project-level .cursor/mcp.json files that override the global one for that repo, the same pattern described under "Global vs project config" above, applied specifically to teams juggling more than one Linear workspace at once. Keep the actual key out of the committed file with ${env:LINEAR_API_KEY} interpolation, and document the expected variable name in a .env.example teammates can copy rather than assuming everyone remembers to set it.

Rate limits

Linear's API enforces a complexity-based budget, not a flat request count: authenticated calls get 250,000 complexity points per hour, and a single query can cost up to 10,000 points depending on how much it asks for in one shot. A prompt like "list every issue across every team with full comment history" burns through that budget far faster than "list my open issues in TEAM" — the complexity cost scales with the size and nesting of what you're requesting, not just the number of calls.

When the budget is exhausted, Linear returns a 429 with a Retry-After header. The MCP server surfaces this as a failed tool call in Cursor rather than a labeled rate-limit message, so a sudden run of tool errors after a burst of broad queries is usually this, not a broken connection. Responses also carry an X-MCP-Toolsets-adjacent X-RateLimit-Remaining-style header on the underlying API responses if you're debugging at the HTTP level; Cursor's chat UI doesn't expose it directly, but Cursor's MCP Logs (see below) will show the raw error.

Practical fix: scope prompts to a specific team, project, or issue rather than the whole workspace, and prefer /readonly or a read-scoped key for exploratory work where you don't need to also enable write tools. If you're running a scripted or repeated workflow against Linear through Cursor's agent (not just interactive chat), treat the same complexity budget as you would any other API rate limit — back off and retry rather than firing the same broad query again immediately.

Troubleshooting

Server never appears in Cursor. Confirm the file is ~/.cursor/mcp.json or .cursor/mcp.json, not a nested editor path. Confirm the top-level key is mcpServers. A VS Code snippet that uses servers plus type http will not load as-is. Invalid JSON drops every server in the file. Linear's Cursor page: validate the JSON and restart Cursor completely.

Remote endpoint does not connect. Linear's Cursor page: you need Cursor v0.48.0 or later for Streamable HTTP, then check firewall and proxy settings. Confirm the URL is https://api.linear.app/mcp/ or your custom Linear host, not an old gist URL.

401 or 403 on every call. The API key is wrong, expired, missing a scope or permission, pending workspace approval, or not authorized for SSO. Linear's generic MCP troubleshooting also says: if you authenticate with an API key, ensure it is valid, has the necessary scopes, and was entered correctly. Regenerate, update the config or the environment variable, restart Cursor.

Tools appear but writes fail. Read-only is on (/readonly in the URL, X-MCP-Readonly, LINEAR_READ_ONLY, or --read-only). Or the key is read-only. Or the Linear account cannot perform that action in the UI. Read-only takes priority over a write tool you named in X-MCP-Tools.

Tool list is huge, or the model picks the wrong tool. Enable fewer toolsets. Unknown toolset names are ignored; they will not fail the server. An invalid tool name in X-MCP-Tools or --tools prevents startup. That asymmetry is documented.

Docker errors. Docker Desktop must be running. For image pull failures, Linear's Cursor page says run docker logout ghcr.io and retry. If the docker command is not found, Docker is not on the PATH Cursor sees.

OAuth in Docker never finishes. Confirm the loopback publish of 127.0.0.1:8085:8085 and LINEAR_OAUTH_CALLBACK_PORT=8085. Confirm nothing else holds 8085. Confirm you are on linear.app with the official image, or that you brought your own app on Enterprise.

Green server, agent says the tool was not found. Cursor has discussed HTTP MCP tools that appear in settings but are not callable from Agent in some builds. Workarounds discussed in Cursor's forum include a new Agent chat, or Settings, Network, HTTP Compatibility Mode, http/1.1, then restart. Not a Linear outage by default.

Still stuck. Debug MCP Server Issues covers reading client logs. Cursor isolates a crashed MCP server from the others.

Frequently Asked Questions

What is the Linear MCP server Cursor IDE setup 2026 path?

Use Linear's hosted remote URL https://api.linear.app/mcp/ with an API key in an Authorization: Bearer header inside ~/.cursor/mcp.json, or run the official ghcr.io/linear/linear-mcp-server Docker image locally. This page is the dedicated Linear MCP server Cursor IDE setup 2026 guide.

What is the exact linear mcp server cursor ide setup for 2026? Add a linear entry under mcpServers in ~/.cursor/mcp.json with url https://api.linear.app/mcp/ and an Authorization: Bearer header carrying a Linear API key (or run ghcr.io/linear/linear-mcp-server locally). Restart Cursor, confirm the green status, then ask it to list your Linear issues. This page is that Cursor-specific path.

Does the Linear MCP server support OAuth in Cursor?
On the remote path, Linear's Cursor install guide says the Linear server currently requires an API key, even though Cursor supports OAuth for some other MCP servers. On the local Docker path, the official image can log in with OAuth on linear.app and keep the token in memory; an API key, if set, wins. Linear's Visual Studio and JetBrains remote OAuth flow is documented for those hosts, not as the Cursor remote setup.

Which toolsets are enabled if I do not specify any?
Linear's configure-toolsets page lists issues, projects, and teams. The repo server-configuration guide lists issues, projects, teams, users. Check the live README if you need the current default.

Can I give Cursor read-only access to Linear?
Yes. Use /readonly on the remote URL, send X-MCP-Readonly, or set LINEAR_READ_ONLY or --read-only locally. Read-only wins over any write tool you named. Pair it with a read-scoped key.

Should I put the config in the project or my home directory?
Use ~/.cursor/mcp.json for a Linear connection you want everywhere. Use .cursor/mcp.json when one project needs its own key, host, or toolsets. If the project file contains an API key, do not commit it.

Can I connect Linear Enterprise?
Yes, on the local Docker path only, with LINEAR_HOST=https://YOUR_LINEAR_ENTERPRISE_HOSTNAME. Linear states Enterprise does not host the remote MCP server. Linear Cloud with custom domain can use https://api.YOUR_CUSTOM_DOMAIN/mcp remotely.

What happened to the old community Linear MCP package?
Linear's Cursor install guide: that package is no longer supported as of April 2025 and is no longer functional. Use https://api.linear.app/mcp/ or ghcr.io/linear/linear-mcp-server.

How do I debug a Linear MCP server that connects but never calls tools?
Check Cursor's MCP Logs (Output panel, Command-Shift-U on macOS or Control-Shift-U on Windows/Linux). Verify the toolsets you enabled match the tools you are requesting. Confirm the API key has the required scopes for each tool. If the server was added before auth completed, toggle it off and on in Customize.

What is the performance impact of enabling all Linear toolsets?
Enabling all toolsets adds 2–3 seconds to Cursor's startup time because the server must enumerate every available tool. Remote-only toolsets like copilot and linear_support_docs_search also increase context overhead. Disable unused toolsets to improve agent accuracy and reduce initialization delay.

Can I run Linear MCP and GitHub MCP in Cursor at the same time?
Yes — add both as separate entries under mcpServers in the same mcp.json, each with its own url and its own Authorization header (a Linear API key for one, a GitHub PAT for the other). There is no combined server; Cursor calls whichever tool a request needs from whichever server has it. See the "Running Linear MCP alongside GitHub MCP" section above for the exact config block.

Why do I get repeated tool failures after a few broad Linear queries in the same session?
This is almost always Linear's complexity-based rate limit, not a broken connection. Authenticated calls get a 250,000 complexity-point budget per hour and a single broad query (everything across every team, with full comment history) can cost up to 10,000 points on its own. Linear returns a 429 with a Retry-After header when the budget runs out; scope prompts to a specific team or project rather than the whole workspace to avoid tripping it.

Looking for GitHub, GitLab, Jira, or Bitbucket?

This URL is Linear issues, projects, and cycles through Linear's official MCP server. GitHub repositories and pull requests are on GitHub MCP Server Cursor IDE Setup. GitLab merge requests are on GitLab MCP Server Cursor IDE Setup. Jira is on Jira MCP Server Cursor IDE Setup. Bitbucket Cloud is on Bitbucket MCP Server Cursor IDE Setup. Do not add GitHub, GitLab, or Jira keys to the Linear url block.

Related guides

Official docs cited