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

Connect your AI Agents to YouTrack in minutes

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

Start building for free

Read docs

YouTrack

Learn more about Merge Agent Handler

Available tools

list_issue_activities

List an issue's change history — field changes, comments, links, and work items — with who changed what and when. Narrow with categories (e.g. ['CustomFieldCategory']) to see only field changes. Set reverse=true for newest first.

list_agiles

List agile boards, including the projects each covers and its current sprint. Returns board IDs needed by listsprints and createsprint.

get_agile

Get one agile board by ID (e.g. '204-0'). Use list_agiles to find board IDs.

list_sprints

List sprints on an agile board, with start and finish dates. Use listagiles to find the board ID. To move an issue onto a sprint use applycommand with 'add Board <board name> <sprint name>'.

get_sprint

Get one sprint by board ID and sprint ID. Use list_sprints to find sprint IDs.

create_sprint

Create a sprint on an agile board. Requires the board ID (from list_agiles) and a name. Start and finish accept ISO dates such as '2026-08-10'.

delete_sprint

Delete a sprint from an agile board. Issues on the sprint are not deleted, only unassigned from it. Use list_sprints to find sprint IDs.

list_articles

List knowledge base articles, optionally filtered with a search query such as 'project: DEMO onboarding'. Omits article bodies to keep the response small — use get_article for full content.

get_article

Get one article including its full Markdown content. Accepts an internal ID ('186-0') or readable ID ('DEMO-A-1'). Use list_articles to find article IDs.

create_article

Create a knowledge base article in a project. Requires projectid (from listprojects) and summary. Pass parentarticleid to nest it under an existing article. Restrict who can read it with permittedusers and permittedgroups (IDs from listusers and listgroups).

update_article

Update an article's title or Markdown content. Accepts an internal ID ('186-0') or readable ID ('DEMO-A-1'). Use get_article first to read the current content.

delete_article

Permanently delete an article and all of its sub-articles. Use list_articles to find article IDs. This cannot be undone.

list_article_comments

List comments on a knowledge base article. Accepts an internal ID ('186-0') or readable ID ('DEMO-A-1'). For issue comments use list_comments instead.

create_article_comment

Add a comment to a knowledge base article. Accepts an internal ID ('186-0') or readable ID ('DEMO-A-1'). Restrict who can read it with permittedusers and permittedgroups (IDs from listusers and listgroups). For issue comments use create_comment instead.

list_attachments

List files attached to an issue, including name, size, MIME type, and a download path relative to the instance URL. Accepts an internal issue ID ('3-0') or readable ID ('DEMO-1').

delete_attachment

Permanently delete a file attached to an issue. Use list_attachments to find attachment IDs. This cannot be undone.

list_comments

List comments on an issue, oldest first. Accepts an internal issue ID ('3-0') or readable ID ('DEMO-1'). Returns comment IDs needed by updatecomment and deletecomment.

create_comment

Add a comment to an issue. Accepts an internal issue ID ('3-0') or readable ID ('DEMO-1'). Set silent=true to skip notifying watchers. Restrict who can read it with permittedusers and permittedgroups (IDs from listusers and listgroups); omit both to inherit the issue's visibility. To comment and change a field in one step, use apply_command with its comment parameter.

update_comment

Edit a comment's text, pin it, or change who can read it. Use listcomments to find comment IDs. Set permittedusers/permittedgroups (IDs from listusers and list_groups) to restrict it, or pass [] for both to lift a restriction. Only the author, or a user with Update Comment permission, can edit it.

delete_comment

Permanently delete a comment from an issue. Use list_comments to find comment IDs. This cannot be undone.

discover_project_fields

List every custom field available on issues in a project, with the exact '$type' and allowed values each one needs. ALWAYS call this before createissue or updateissue when setting Priority, State, Assignee, or any custom field — those writes fail without the correct '$type', which cannot be guessed. Each field includes a ready-to-copy 'example' payload.

list_custom_fields

List custom fields defined across the whole instance. Use discoverprojectfields instead when building an issue payload — this tool shows global definitions, not the values a specific project accepts.

list_issues

Search issues using YouTrack query syntax, e.g. 'project: DEMO State: Open assignee: me' or '#Unresolved'. Sort by appending 'sort by: created desc' to the query. Pass customfields (e.g. ['Priority','State']) to include those values. Returns lean fields by default; widen with the fields parameter. Use getissue for one issue's full detail.

get_issue

Get one issue with its description and custom field values. Accepts an internal ID ('3-0') or a readable ID ('DEMO-1'). Use list_issues to find issue IDs.

create_issue

Create an issue. Requires projectid (from listprojects) and summary. To set Priority, State, Assignee, or any other custom field, ALWAYS call discoverprojectfields first — it returns the exact '$type' and allowed values each field needs, which cannot be guessed. Unset fields take project defaults. Restrict reads with permittedusers/permittedgroups (IDs from listusers and listgroups).

update_issue

Update an issue's summary, description, or custom fields. Accepts an internal ID ('3-0') or readable ID ('DEMO-1'). To change Priority, State, Assignee, or any custom field, ALWAYS call discoverprojectfields first for the exact '$type' and allowed values. For state transitions and bulk edits, apply_command is often simpler.

delete_issue

Permanently delete an issue and its comments, attachments, and work items. Accepts an internal ID ('3-0') or readable ID ('DEMO-1'). This cannot be undone.

count_issues

Count issues matching a YouTrack query without fetching them, e.g. 'project: DEMO #Unresolved'. Cheaper than paginating list_issues when only the total is needed.

apply_command

Apply a YouTrack command to one or more issues, e.g. 'State Fixed', 'Priority Critical', 'for jane.doe', 'tag regression', or 'add Board Sprint 5'. The fastest way to change state, assign, or bulk-edit — no '$type' needed, unlike updateissue. Use getcommand_suggestions to check syntax first.

list_issue_links

List an issue's links, grouped by link type and direction. Returns the directed link IDs (e.g. '173-1s' outward, '173-1t' inward) that linkissues and unlinkissues require. Accepts an internal ID ('3-0') or readable ID ('DEMO-1').

list_issue_link_types

List the link types configured on the instance, such as Relates, Depend, Duplicate, and Subtask, with their outward and inward phrasings. To link two issues use listissuelinks, which returns the directed link IDs link_issues needs.

link_issues

Link one issue to another. linkid is a directed link type ID such as '173-1s' (outward) or '173-1t' (inward) — call listissuelinks on any issue to see the exact IDs and what each direction means. Alternatively use applycommand with a command like 'depends on DEMO-4'.

unlink_issues

Remove a link between two issues. linkid is the directed link type ID (e.g. '173-1s') — use listissue_links to find which link currently holds the target issue.

list_projects

List projects on the instance. Returns the internal project IDs (e.g. '0-0') that createissue, createarticle, and discoverprojectfields require, plus the short name used as the issue ID prefix.

get_project

Get one project by its internal ID (e.g. '0-0'). Use list_projects to find IDs.

create_project

Create a project. Requires name, shortname (the issue ID prefix, must be unique), and leaderid — use listusers or getcurrent_user to get a valid leader ID. Requires admin permissions.

update_project

Update a project's name, short name, description, owner, or archived state. Use list_projects to find the project ID. Requires admin permissions.

delete_project

Permanently delete a project and every issue and article in it. Use listprojects to find the project ID. This cannot be undone — consider updateproject with archived=true instead. Requires admin permissions.

list_project_team

List the users on a project's team — the people assignable to its issues. Use list_projects to find the project ID.

list_saved_queries

List saved searches visible to the current user. Each returns a query string that can be passed straight to list_issues as the query input.

get_search_suggestions

Get valid completions for a partial issue search query, e.g. 'stat' suggests 'State:'. Use this to build a correct query for list_issues when unsure of the field names available on this instance.

get_command_suggestions

Get valid completions for a partial YouTrack command against specific issues, e.g. 'stat' suggests the State values those issues accept. Call this before apply_command when unsure of the exact command syntax or allowed values.

list_tags

List issue tags visible to the current user. Returns the tag IDs that addissuetag and removeissuetag require. To find issues by tag, pass 'tag: <name>' to list_issues.

create_tag

Create an issue tag. Set untagonresolve=true to have YouTrack remove it automatically when an issue is resolved. Use addissuetag to apply it.

delete_tag

Permanently delete a tag and remove it from every issue carrying it. Use list_tags to find tag IDs. This cannot be undone.

add_issue_tag

Apply an existing tag to an issue. Use listtags for tag IDs, or createtag first. Accepts an internal issue ID ('3-0') or readable ID ('DEMO-1').

remove_issue_tag

Remove a tag from an issue. The tag itself is not deleted. Use list_tags or read the issue to find the tag ID.

get_current_user

Get the user the permanent token belongs to. Useful for resolving 'me' in queries and for supplying leaderid to createproject.

list_users

List user accounts, optionally filtering server-side with query (matches login, full name, or email). Returns the internal user IDs and logins that assignee fields, createproject, and creatework_item need.

get_user

Get one user by internal ID (e.g. '2-1'). Use listusers to find user IDs, or getcurrent_user for the authenticated account.

list_groups

List user groups on the instance. Pass query to filter by name substring. Returns the group IDs needed by permittedgroups on createcomment, createissue, and createarticle, and by group-typed custom fields.

list_group_members

List the users in a group. Use listgroups to find group IDs. Returns the user IDs needed by permittedusers on createcomment, createissue, and create_article.

validate_credential

Validate the YouTrack instance address and permanent token by fetching the current user. Use this to confirm setup before calling other tools.

list_work_items

List time-tracking entries across issues, for timesheet and reporting use. Filter server-side by query (e.g. 'project: DEMO'), date range, and author. Use listissuework_items instead when you only need one issue's entries.

list_issue_work_items

List the time logged against one issue. Accepts an internal ID ('3-0') or readable ID ('DEMO-1'). Returns work item IDs needed by deleteworkitem. Use listworkitems for cross-issue reporting.

create_work_item

Log time against an issue. Requires the issue ID and minutes. Pass typeid from listworkitemtypes to categorize the entry, and date (e.g. '2026-08-05') to backdate it. Time tracking must be enabled on the issue's project.

delete_work_item

Permanently delete a time-tracking entry from an issue. Use listissuework_items to find work item IDs. This cannot be undone.

list_work_item_types

List the work item types configured on the instance, such as Development or Testing. Call this before createworkitem to get a valid type_id.

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}