How to connect a Linear MCP to Cursor (4 steps)

Developers building tools that create or update Linear issues need to understand the data model before the code can be correct.

What are the valid workflow state IDs for a given team? What does an issue object actually return? What field holds the priority value, and what are its valid inputs?

A Slack bot that converts support messages into tickets, a release script that closes issues on deploy, a triage tool that routes issues by team: all of these depend on workspace-specific identifiers that only appear in a real API response.

Without the MCP connection, answering those questions means leaving Cursor, authenticating against Linear's API separately, running test queries, and copying responses back into the session where the integration code lives.

To help your developers inspect Linear's data model and query real workspace data without leaving Cursor, we'll show you how to connect Linear with Merge Agent Handler's Linear MCP server.

How it works

Merge Agent Handler connects Cursor to the Linear API through the Merge CLI.

Install the CLI, authenticate once, and run a single setup command from your project root.

That command writes a ## Merge CLI section to the project's .cursorrules file, which tells Cursor's agent when to call merge search-tools and merge execute-tool to reach Linear.

Once connected, Merge handles Linear's OAuth credentials and token refresh so you never store access tokens locally or rewire auth when they expire.

Here's the registration command:

merge setup cursor

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Cursor installed
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A Linear account with sufficient workspace permissions

If you want to connect Merge Agent Handler's Linear MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Run the following to install the Merge CLI and confirm it's available: pipx install merge-api

Verify your installation: merge --version

Related: How to use the Linear MCP in Claude Code

2. Log in to Merge

Authenticate the CLI with your Merge Agent Handler account: merge login

This links the CLI to your account so it can make authorized requests to Linear on your behalf.

3. Connect the CLI to Cursor

Run the following from the root of the project where you want to use Merge tools:

merge setup cursor

This writes a ## Merge CLI section to .cursorrules so Cursor knows to use the CLI for third-party services. The command is idempotent, safe to re-run if you need to reset.

4. Authenticate Linear

Open a Cursor chat in your project and start with a query that reflects real integration work. For example: "Fetch the complete list of workflow states for the Engineering team, including their IDs, names, and types, so I can write correct state transition logic in my integration."

The first time you invoke a Linear tool, a Magic Link will appear to complete connector authentication.

{{this-blog-only-cta}}

Linear MCP FAQ

In case you have more questions on setting up and using the Linear MCP in Cursor, we've addressed several more commonly-asked questions below.

What can you do once the Linear MCP is connected to Cursor?

With Linear connected, Cursor can:

• Fetch workflow state IDs and types before writing state transition code: retrieve the full set of states for a specific team, including their UUIDs and type classifications (triage, started, completed, cancelled), so the transition logic you write uses the correct identifiers before you run it against the API

• Look up team identifiers before writing issue creation code: query the workspace's team list and their IDs before writing code that creates issues on behalf of a specific team, so team assignment in your payload is correct from the first call

• Inspect label IDs and names before writing code that assigns them: fetch the full label set for a team or workspace before writing code that tags issues programmatically, so label references in your integration match what actually exists in the workspace

• Check priority field values before writing conditional logic: retrieve the priority enum values Linear accepts before writing branching logic that maps your system's severity levels to Linear's priority field

• Retrieve cycle field structure before writing sprint-assignment code: inspect how cycles are structured and what fields they expose before writing code that adds issues to a sprint, so field names and ID references are correct

• Validate issue relation types before writing dependency-linking code: fetch the valid relation type identifiers (blocks, duplicate, related) before writing code that links issues together, so relation payloads are correctly formed before testing

Why use Merge Agent Handler vs. a self-hosted Linear MCP server?

You can connect directly to Linear's API using a personal API key. Linear's REST and GraphQL endpoints are well-documented, and for a single developer building against their own workspace the setup is fast.

The access control problem appears when you scale beyond one developer or one agent.

A personal API key carries the permissions of the account that generated it. Sharing it across agents or team members means every agent operates with the same level of access, with no way to restrict which teams, projects, or operations a given agent can reach. Key rotation requires updating every system that holds the key at once.

Merge Agent Handler handles Linear authentication centrally.

You define exactly which Linear operations each agent is allowed to call: an agent that monitors issue status, for example, can read issues and workflow states without reaching write operations like create or delete.

Every call is also logged with the timestamp, tool, and inputs, so you have a full audit trail of what each agent read or modified.

For teams running multiple agents against a shared Linear workspace, that combination of scoped access and central logging is the difference between a controlled deployment and a shared credential problem.

Why connect Linear to Cursor?

Linear's API data, including workflow state IDs, team identifiers, label sets, and cycle structures, isn't something you can look up in documentation alone.

These values are workspace-specific: a state called "In Review" in one workspace has a different UUID than the same state in another. The code that creates, transitions, or links Linear issues can only be correct once you know the actual identifiers from the workspace it will run against.

Connecting Linear to Cursor puts that discovery step inside the editor.

This means that when you're writing a state transition and need the IDs for the target states, you can query them; or when you're building issue creation logic and need the team identifier, you can fetch it. In short, you don't have to leave the editor to get the data your code depends on.