MCP Server

Model Context Protocol (MCP) is a standard that lets applications such as chatbots, AI assistants, and coding agents communicate with services like YouTrack in a consistent way. In MCP terminology, these applications are MCP clients, and YouTrack provides the MCP server.

The YouTrack MCP server gives clients access to read and update YouTrack data through predefined MCP tools, subject to the permissions of the authenticated YouTrack account. These tools can search for issues and articles, create and update content, add comments and attachments, manage tags and issue links, and log work.

MCP Endpoint and Authorization

Use the endpoint and authorization details in this section when you add YouTrack to an MCP client.

MCP Endpoint URL

YouTrack exposes its MCP server over the Streamable HTTP transport at https://<instance-name>.youtrack.cloud/mcp. Any MCP client that supports Streamable HTTP can connect directly to this endpoint.

Replace <instance-name> with the name of your YouTrack Cloud site. If the site uses a custom domain or another base URL, append /mcp to that base URL instead.

Choose an Authorization Method

YouTrack supports OAuth authorization and permanent token authorization for MCP connections.

Method	Use case
OAuth	Use OAuth when each user should approve access with their own YouTrack account. The MCP client receives an access token without requiring the user to create and copy a permanent token. The OAuth client can be registered automatically with CIMD or manually by a YouTrack system administrator. For details, see Set Up OAuth.
Permanent token	Use a permanent token when the MCP client doesn't support OAuth or when an integration must always act as one YouTrack account. For example, a shared service can use a permanent token that belongs to a dedicated account for all requests. Every request then has the permissions of that account.

Method

Use case

OAuth

Use OAuth when each user should approve access with their own YouTrack account. The MCP client receives an access token without requiring the user to create and copy a permanent token.

The OAuth client can be registered automatically with CIMD or manually by a YouTrack system administrator. For details, see Set Up OAuth.

Permanent token

Use a permanent token when the MCP client doesn't support OAuth or when an integration must always act as one YouTrack account.

For example, a shared service can use a permanent token that belongs to a dedicated account for all requests. Every request then has the permissions of that account.

Set Up OAuth

After you choose OAuth as the authorization method, determine how to register the OAuth client. Choose the registration method that the MCP client supports, then ask a YouTrack system administrator to complete the required setup.

Automatic registration with a Client ID Metadata Document (CIMD). For an MCP client that supports CIMD, ask a system administrator to open Administration > Access Management > OAuth Clients and enable Allow automatic OAuth client registration via CIMD.
After the administrator enables this setting, connect the MCP client using the YouTrack MCP endpoint URL. For details, see Automatic OAuth Client Registration.
Manual registration. If the MCP client doesn't support CIMD, obtain its redirect Uniform Resource Identifier (URI) and other OAuth requirements from the client provider. Ask a system administrator to create an OAuth client, then add the generated client ID to the MCP client. For a confidential client, also add the client secret.
For instructions, see Create an OAuth Client Manually.

Check the MCP client documentation to confirm its registration method and OAuth requirements. YouTrack supports automatic registration with CIMD but doesn't support OAuth Dynamic Client Registration. For protocol details, see OAuth 2.0 Authorization in the Developer Portal.

Connect an MCP Client

Use these instructions for any MCP client that connects directly to YouTrack over Streamable HTTP. Before you start, confirm that the client accepts an MCP server URL and supports your selected authorization method.

With OAuth, each user approves access using their YouTrack account. Complete the applicable OAuth client registration before you connect.

To connect an MCP client with OAuth:

Add the YouTrack MCP endpoint URL to the MCP client.
If the client requests OAuth credentials, enter the client ID and, for a confidential client, the client secret from the manually registered OAuth client.
Start authorization from the MCP client.
On the YouTrack authorization page, review the requested access and approve the connection.
Return to the MCP client and finish the connection setup.
Confirm that the client lists the YouTrack MCP tools. Test the connection with a read-only request, such as finding issues assigned to you.

A permanent token authorizes every request as the YouTrack account that owns the token. For a shared integration, use a dedicated account with only the required permissions.

To connect an MCP client with a permanent token:

Generate a permanent token for the account and select YouTrack as the scope. For instructions, see Create a Permanent Token.
Add the YouTrack MCP endpoint URL to the MCP client.
Add an HTTP authorization header with the value Bearer <token>, where <token> is the permanent token.
Confirm that the client lists the YouTrack MCP tools. Test the connection with a read-only request.

The following command adds the YouTrack MCP server to Claude Code using a permanent token. Replace the placeholders with the MCP endpoint URL and permanent token for your connection.

                    claude mcp add --header "Authorization: Bearer <token>" --transport http youtrack <youtrack-mcp-endpoint-url>
                

If the MCP client reports that automatic client registration isn't supported, ask a YouTrack system administrator to enable CIMD. If the MCP client doesn't support CIMD, register an OAuth client manually.
If the MCP client can't find the server, check that the URL uses HTTPS, starts with the correct base URL for the YouTrack Cloud site, and ends with /mcp.
If OAuth authorization fails, verify the registered redirect URI and OAuth client credentials. If the settings are correct, remove the connection from the MCP client and authorize it again.
If expected data is missing, verify the permissions and visibility restrictions for the authenticated account. For details, see Check Data Visibility.
If permanent token authorization fails, verify that the token has the YouTrack scope and hasn't been deleted.

Connect ChatGPT and Claude

ChatGPT and Claude provide YouTrack connectors. Connector availability and setup depend on the provider plan, the YouTrack site address, and the YouTrack version.

ChatGPT lists the YouTrack connector as a plugin. The plugin requires YouTrack 2026.2.18687 or later and automatic OAuth client registration through CIMD. The plugin is available for ChatGPT Business and Enterprise plans.

The plugin accepts the YouTrack MCP endpoint URL for any domain. ChatGPT must be able to reach the endpoint over the public internet.

To connect YouTrack using the ChatGPT plugin:

Ask a YouTrack system administrator to enable Allow automatic OAuth client registration via CIMD.
Open the YouTrack plugin in ChatGPT and start the connection.
Enter the YouTrack MCP endpoint URL.
On the YouTrack authorization page, review the requested access and approve the connection.
Enable YouTrack in a conversation and test the connection with a read-only request.

If the YouTrack plugin isn't available for your plan, add YouTrack as a custom plugin when your ChatGPT plan and workspace settings support plugin creation. With CIMD enabled, provide the plugin name and YouTrack MCP endpoint URL. If CIMD isn't enabled, configure a manually registered OAuth client.

For current instructions, see Connect from ChatGPT.

The verified YouTrack connector requires YouTrack 2026.2.18687 or later and automatic OAuth client registration through CIMD.

YouTrack site	Connection method
YouTrack Cloud on a `*.youtrack.cloud` address	Use the verified connector in the Claude Connector Directory.
YouTrack Cloud with a custom domain	Use the verified connector with the site's original `*.youtrack.cloud` address followed by `/mcp`, or add a custom connector.

To connect a YouTrack Cloud site using the verified Claude connector:

Ask a YouTrack system administrator to enable Allow automatic OAuth client registration via CIMD.
Open the YouTrack connector in the Claude Connector Directory and click Connect.
Enter the site's MCP endpoint URL: https://<instance-name>.youtrack.cloud/mcp.
On the YouTrack authorization page, review the requested access and approve the connection.
Enable the connector in a conversation and test it with a read-only request.

To connect using a custom connector, follow the Claude instructions for custom connectors. For a Cloud site with a custom domain, this option lets you use the custom-domain endpoint instead of the site's original *.youtrack.cloud address. The YouTrack site must be reachable from Anthropic's cloud infrastructure.

To add YouTrack as a custom connector for a Claude Team or Enterprise plan:

Ask a Claude Owner or Primary Owner to open Organization settings > Connectors.
Add a custom web connector named YouTrack and provide the YouTrack MCP endpoint URL.
If Claude requests OAuth credentials, enter the client ID and, for a confidential client, the client secret from the manually registered OAuth client.
Complete the setup and approve access in YouTrack.
Confirm that the connector is active and test it with a read-only request.

To add YouTrack as a custom connector for an individual Claude plan:

Open Customize > Connectors, click the plus button, and select Add custom connector.
Enter YouTrack as the connector name and provide the YouTrack MCP endpoint URL.
If Claude requests OAuth credentials, open Advanced settings and enter the client ID and, for a confidential client, the client secret from the manually registered OAuth client.
Complete the setup and approve access in YouTrack.
Confirm that the connector is active and test it with a read-only request.

Optional MCP Endpoint Parameters

Add query parameters to the MCP endpoint URL to control which tools are available to the client and how the server describes their output. The server applies tool filters both when it lists tools and when the client invokes a tool. A tool that a filter excludes can't be invoked through that endpoint URL. For parameters that accept lists, separate multiple values with commas.

Parameter	Description
`tools`	Make only the listed tool names available. For example, `/mcp?tools=search_issues,get_issue`.
`ignoreTools`	Exclude the listed tool names. For example, `/mcp?ignoreTools=find_user,manage_issue_tags`.
`toolSubsets`	Make only tools from the listed functional subsets available. Supported predefined subsets are `issue`, `article`, `project`, `group`, `user`, and `time-tracking`. The `add_attachment` tool doesn't belong to a functional subset, so specifying this parameter excludes it. For example, `/mcp?toolSubsets=issue,article`.
`readOnlyTools`	Filter tools by their read-only annotation. `true` returns only tools whose read-only annotation is set to `true`. `false` returns only tools whose read-only annotation is set to `false`. Omit the parameter to return tools regardless of their read-only annotation.
`customToolPackages`	Make custom MCP tools from the listed app packages available to the connection. Specify each package by name. For example, `/mcp?customToolPackages=app-name1,app-name2`.
`enableToolOutputSchema`	Set this parameter to `true` to include each tool's output JavaScript Object Notation (JSON) Schema in the `tools/list` response. For example, `/mcp?enableToolOutputSchema=true`. Output schemas are available to MCP clients that use protocol version 2025-06-18 or later. The server includes a schema only when the tool provides one. The `add_attachment` tool doesn't currently provide an output schema. Custom MCP tools can also define output schemas.

MCP Tools

YouTrack provides predefined MCP tools for issues, articles, attachments, projects, groups, users, and time tracking. The tools become available when the MCP client connects to the YouTrack MCP server.

Issue

Use issue tools to search for issues, create and update issues or drafts, manage comments and tags, and link related issues.

Name	Description	Sample Prompt
`search_issues`	Searches for issues using YouTrack query syntax. The query can combine attribute filters, keywords, and free text. Returns a paginated list with basic issue fields and selected custom fields.	Find all unresolved bugs assigned to me in the Mobile App project.
`get_issue_fields_schema`	Returns the JSON Schema for custom fields in a project, including fields and values relevant to issue creation and updates.	Which fields and values are available for issues in project WEB?
`create_issue`	Creates an issue in a project. Project-specific custom fields can be required. The tool can restrict issue visibility to specified users or groups and returns the new issue ID and URL. The returned `createdIssue.id` value can be passed as the target for `add_attachment`.	Create an issue in project BACK with the summary "Fix authentication timeout", set Priority to High, assign it to alex, and restrict visibility to the Security Team.
`create_draft_issue`	Creates an issue draft in a project. Project workflows can initialize its description from an issue template. The draft is visible only to the current user and can be updated later. Returns the draft ID and URL.	Create an issue draft in project MKT with the summary "Revise homepage hero section".
`update_issue`	Partially updates an issue or draft. It can change the summary, description, and custom fields; star or unstar the issue or draft for the current user; and add or remove the current user's vote. When the current user stars the issue or draft, YouTrack sends notifications according to the subscription settings for the Star tag. It cannot change issue visibility. Returns the issue ID and a summary of applied changes.	Change the State of WEB-132 to In Progress and set its Priority to Major.
`get_issue`	Returns an issue or draft with its summary, description, URL, project, reporter, links, attachments, tags, votes, recent comments, the number of linked VCS commits, and visible custom fields. For a draft, the description includes content added by project workflows. The custom fields contain details such as Type, State, Assignee, Priority, and Subsystem when these fields are available and visible.	Show the details for issue BACK-249.
`change_issue_assignee`	Assigns an issue to the specified user. A null assignee unassigns the issue.	Assign issue DEV-102 to julia.
`add_issue_comment`	Adds a Markdown comment to an issue. The tool can restrict comment visibility to specified users or groups. It returns a `commentId` value that can be passed as the target for `add_attachment`.	Add a comment to APP-56 that says, "Please include the API documentation before closing", and make it visible to the Feature Development team.
`get_issue_comments`	Returns paginated issue comments with their authors, text, timestamps, and attachments.	List the comments for issue UX-87.
`get_saved_issue_searches`	Returns the current user's favorite saved issue searches and their query strings. The query strings can be used in issue searches. The response is paginated.	Show my favorite saved issue searches.
`manage_issue_tags`	Adds a tag to or removes a tag from an issue. Tags can be identified by ID or exact name. If the tag is unknown or inaccessible, the tool returns similar-name suggestions. Returns the issue ID and updated tags.	Add the tag "urgent" to issue API-144.
`link_issues`	Links two issues using the specified inward or outward link type. Returns updated counts for the target issue's link types.	Link DOCS-12 to DEV-99 using the "relates to" link type.

Article

Use article tools to search, read, create, and update Knowledge Base articles.

Name	Description	Sample Prompt
`create_article`	Creates an article in a project. The article can be a sub-article and can have visibility restricted to specified users or groups. Returns the article ID and URL.	Create an article in project COMP from the previous response and restrict its visibility to the Legal team.
`update_article`	Updates an article's summary, content, or parent. New content replaces the existing content unless the append option is enabled. Returns the article ID and URL.	Append the previous response to article COMP-A-42.
`get_article`	Returns an article's summary, content, sub-articles, tags, and visibility settings. Supports line-based pagination for long content.	Show the content of article DOCS-A-17 and list its sub-articles.
`search_articles`	Searches Knowledge Base articles using YouTrack query syntax. The query can combine attribute filters, keywords, and free text. Returns paginated basic article details and the content lines that match the query.	Find articles about API authentication in the Developer Docs project that sarah created.

Project

Use project tools to find projects and retrieve project settings.

Name	Description	Sample Prompt
`find_projects`	Finds projects whose names or keys contain a case-insensitive substring. Returns project keys and names in a paginated response.	Find projects with "CRM" in the name or key.
`get_project`	Returns project details, team information, and time tracking settings. Time tracking settings include available work item types and attribute values.	Show the details and time tracking settings for project CP.

Group

Use group tools to find user groups or project teams and list their members.

Name	Description	Sample Prompt
`find_user_groups`	Finds user groups or project teams whose names contain a case-insensitive substring. The response is paginated.	Find groups and project teams with "Design" in the name.
`get_user_group_members`	Lists members of a user group or project team. A project team is a group associated with a specific project. The response is paginated.	List the members of the QA Engineers group.

User

Use user tools to find a user or retrieve the authenticated account.

Name	Description	Sample Prompt
`find_user`	Finds a user by exact login or email address. Returns the login, full name, email address, and local time zone. The value `me` identifies the current user.	Find the user with the email address alex.rocha@company.com.
`get_current_user`	Returns the login, email address, full name, and time zone for the authenticated account.	Show my account details.

Time Tracking

Use the time tracking tool to add work items to issues.

Name	Description	Sample Prompt
`log_work`	Adds a work item to an issue. Duration is required. Date, work type, description, and work item attributes are optional. Available work types and attribute values depend on the project settings.	Log 90 minutes of work on DEV-203 with the description "Refactored payment module".

Custom MCP Tools

Create custom MCP tools when the predefined tools don't cover your use case. Add the scripts to an app package and make them available through the YouTrack MCP server.

For instructions, see Custom MCP Tools in the Developer Portal.

27 October 2026