Merge Unified's Linear integration Merge Agent Handler's Linear MCP server

Connect your AI Agents to Linear in minutes

Merge lets you securely connect your agents to Linear and thousands of tools instantly

Start building for free

Read docs

Linear

Learn more about Merge Agent Handler

Available tools

get_comments

List comments from Linear, optionally scoped to one issue via issueid (accepts a UUID or an identifier like 'ENG-142'; use getissues to find issues). Filter server-side by bodycontains (substring) or createdafter. Supports cursor pagination.

get_comment

Get a single Linear comment by id. Use get_comments to find comment ids on an issue.

create_comment

Add a comment to a Linear issue. issueid accepts a UUID or an identifier like 'ENG-142'; use getissues to find issues. Body is Markdown.

update_comment

Edit the body of an existing Linear comment. Use get_comments to find comment ids.

resolve_comment

Resolve a Linear comment thread by comment id. Use get_comments to find comment ids.

unresolve_comment

Reopen a resolved Linear comment thread by comment id. Use get_comments to find ids.

list_cycles

List cycles (sprints) from Linear, filterable by teamid (use getteams) and isactive. Cycles belong to one team. Use this to discover cycle ids for createissue/update_issue.

get_issue_labels

List issue labels from Linear, with server-side name (substring) and teamid filters plus cursor pagination. Use this to discover valid label ids before setting labelids on createissue/updateissue; only non-group (leaf) labels can be applied to issues.

create_issue_label

Create a Linear issue label. Requires a name; teamid (use getteams) scopes it to one team, omit for a workspace-level label. Optional hex color and description.

list_issue_statuses

List workflow states (issue statuses) from Linear, filterable by teamid (use getteams) and state category. State ids are team-specific — use this to discover valid stateid values before setting them on createissue/update_issue.

get_issues

List issues from Linear with server-side filters (team, assignee, project, project milestone, state, priority, title text, label, updated-after date) and cursor pagination. Use getteams/getusers/getprojects/listprojectmilestones/listissuestatuses to find filter ids. For one known issue use getissue instead. Text search covers TITLES ONLY — descriptions and comments are not searched.

get_issue

Get a single Linear issue by id (UUID) or identifier like 'ENG-142'. Use get_issues to search when the id is unknown.

create_issue

Create a Linear issue. Requires teamid (use getteams). Optional: description, priority 0-4, assigneeid (getusers), stateid (listissuestatuses), labelids (getissuelabels, leaf labels only), projectid (getprojects), cycleid (listcycles), parentid, duedate, subscriber_ids.

update_issue

Update a Linear issue by id or identifier like 'ENG-142': title, description, priority 0-4, estimate, assigneeid (getusers), stateid (listissuestatuses), labels (getissuelabels), project/cycle/parent, duedate, team transfer. To CLEAR a field use its unset_* flag, not null.

archive_issue

Archive a Linear issue by id or identifier like 'ENG-142'. Archiving is Linear's delete; the issue disappears from default views but can be restored in the app.

list_project_milestones

List Linear project milestones (dated checkpoints inside a project) with cursor pagination. Filters server-side by projectid (use getprojects), name substring, target-date range, and updatedafter. Linear has no server-side status filter — read each milestone's status field instead. For a milestone's issues call getissues with projectmilestoneid.

get_project_milestone

Get one Linear project milestone by id (UUID): name, description, target date, status, and progress. Use listprojectmilestones to find milestone ids. For the issues in the milestone call getissues with projectmilestone_id.

get_projects

List projects from Linear. Filter server-side by name (substring, case-insensitive), state, health, or lead; supports cursor pagination and include_archived. Use this to discover project ids for other tools. Prefer the default limit (50) with pagination — large limits can exceed Linear's query-complexity cap and fail.

list_project_statuses

List the workspace-defined project statuses (e.g. Backlog, Planned, In Progress). Use this to find status ids for createproject/updateproject's statusid; each status also shows its fixed type, which is what getprojects' state filter matches.

get_project

Get a single Linear project by id. Use get_projects to search by name when the id is unknown.

create_project

Create a Linear project. Requires name and teamids (use getteams to find team ids). Optional: description, leadid/memberids (getusers), startdate, target_date (YYYY-MM-DD).

update_project

Update a Linear project by id: name, description, lead, status, priority, teams, or dates. Use get_projects to find project ids.

archive_project

Archive a Linear project by id. Archiving hides the project from default views; it can be restored in the app. Use get_projects to find project ids.

get_project_updates

List project status updates from Linear, optionally scoped to one project via projectid (use getprojects to find project ids). Supports cursor pagination and include_archived.

get_project_update

Get a single Linear project update by id. Use getprojectupdates to find update ids.

create_project_update

Post a status update on a Linear project. Requires projectid (use getprojects) and a Markdown body; optional health: onTrack, atRisk, or offTrack.

update_project_update

Edit an existing Linear project update's body or health by id. Use getprojectupdates to find update ids.

archive_project_update

Archive a Linear project update by id. Use getprojectupdates to find update ids.

unarchive_project_update

Restore an archived Linear project update by id. Use getprojectupdates with include_archived=true to find archived update ids.

create_issue_relation

Link two Linear issues, e.g. mark one as blocking another or as a duplicate. Both ids accept a UUID or an identifier like 'ENG-142'; use getissues to find issues. Linear adds the inverse edge automatically, so create the relation once, in one direction only. Use getissue_relations to see existing links first.

get_issue_relations

List the relations on a Linear issue in BOTH directions: what it blocks, what blocks it, duplicates and related links. Each result carries a direction field, so type='blocks' with direction='incoming' means the issue you asked about is blocked by the other one. issueid accepts a UUID or an identifier like 'ENG-142'. Returns relation ids for deleteissue_relation.

delete_issue_relation

Remove a link between two Linear issues. Takes the relation's own id, not an issue id; use getissuerelations to find it. Removing a relation also removes the inverse edge Linear created with it.

create_attachment

Attach a link to a Linear issue, e.g. a PR, doc or dashboard. issueid accepts a UUID or an identifier like 'ENG-142'. The url is the attachment's identity: reusing a url already on the issue updates that attachment rather than adding a second one. Use getattachments to see what is already attached.

get_attachments

List the links attached to a Linear issue, such as PRs, docs and dashboards. issue_id accepts a UUID or an identifier like 'ENG-142'.

get_teams

List teams from Linear. Filter server-side by name (substring, case-insensitive) or key (the exact short code like 'ENG' that prefixes issue identifiers — never pass search text as key). Supports cursor pagination. Use this to discover team ids for other tools.

get_team

Get a single Linear team by id, including its members. Use get_teams to find team ids (or to search by name/key).

create_team

Create a Linear team. Requires a name; the short key (max 7 chars, e.g. 'ENG') is auto-generated when omitted.

update_team

Update a Linear team's name, key, or description by team id. Use get_teams to find team ids.

get_users

List users in the Linear workspace. Filter server-side by name (substring), email (exact), active status, or is_me=true for the authenticated user. Supports cursor pagination. Use this to discover user ids for assignee/lead/member fields. Linear has no user create/update API.

get_user

Get a single Linear user by id. Use getusers to find user ids (or filter isme=true for the authenticated user).

validate_credential

Validate Linear credentials by fetching the authenticated user. Verifies credentials during setup.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Linear MCP server

What makes Merge Agent Handler’s Linear MCP server better than alternative options?

Managed authentication and credential lifecycle: Merge handles connector onboarding, dynamic auth flows, token management, and credential validation so agents can call Linear tools securely without handling OAuth flows directly
‍Security gateway with DLP: Tool inputs and outputs are scanned for sensitive data. You can also set rules to block, redact, or log certain agent behaviors. This capability isn't provided by standalone MCP servers
‍Real-time observability and complete audit logs: Merge provides full tool-call logging, searchable activity history, and visibility into every API request made by an agent. This creates a comprehensive audit trail ‍
Connector Studio for customization: Teams can modify Linear’s connector, add new tools, or customize existing ones

What are popular tools for Linear’s MCP server?

Issue Tools: Find, create, update, or retrieve issues by using tools like get_issue, create_issue, and update_issue
Project Tools: Query or update project data via tools like archive_project, create_project, and get_projects
Comment Tools: Add, update, or retrieve comments on issues with tools like resolve_comment, create_comment, and get_comment

What are some common use cases for the Linear MCP server?

Combine data sources for broader insights: Your analysts can combine information from Linear with other data sources (e.g., your data warehouse) to uncover broader insights, such as the impact product bugs have on feature adoption
Get context on issues or projects: Your support team can retrieve information on specific issues from an app like Slack to understand their status, details, and history
Receive consistent updates: Your product leadership team can receive weekly summaries of the product-specific tickets created in Linear over the past week within Slack