Connect your AI Agents to YouTrack in minutes
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.
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'). 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. To comment and change a field in one step, use apply_command with its comment parameter.
update_comment
Edit a comment's text or pin it. Use list_comments to find comment IDs. Only the comment's 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. Fields left unset take their project defaults.
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. Group names are used when restricting comment visibility or setting group-typed custom fields.
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.
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}
11Open 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}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 }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}FAQs on using Merge's YouTrack MCP server
FAQs on using Merge's YouTrack MCP server
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
