Remote MCP Server

Model Context Protocol (MCP) is a new standard that lets apps like chatbots and other AI tools talk to other services, like YouTrack, in a consistent and safe way. The YouTrack MCP server gives these tools real-time access to read and update issues in YouTrack, using your own account permissions. It includes a set of built-in tools you can use to find, create, and update things like issues and comments.

YouTrack supports connections to local and remote clients, which means you can use whichever connection type is supported by your AI tools.

Remote MCP Client Connections

This type of connection is suitable for cloud-based applications that can communicate using HTTP. For example, automation tools like n8n and OpenAI's Agent Kit, integration platforms like Zapier and Make, or coding agents like Claude Code and Cursor.

To connect with a Remote MCP Client:

Generate a permanent token for your YouTrack account, selecting YouTrack as the scope. For specific instructions, see Create a Permanent Token.

Enter the following variables in the settings for your AI tool:

Variable	Description
MCP endpoint	Enter the base URL for your YouTrack site, followed by the `/mcp` endpoint. For example, `https://my-company.youtrack.cloud/mcp`.
HTTP header	Provide the authorization token to be used in the header for HTTP requests to the remote MCP client. For example, `Authorization: Bearer <token>`, where the value for the `<token>` is the permanent token you generated for your YouTrack account.

Here's a sample command that shows you how to connect to Claude Code. When using it, replace the placeholders with the base URL for your YouTrack site and your permanent token.

            claude mcp add --transport http YouTrack <your-youtrack-base-URL>/mcp --header "Authorization: Bearer <token>"
        

Local MCP Client Connections

This type of connection is appropriate for local AI tools and chat apps that connect directly from your computer using the mcp-remote proxy. If you're working with JetBrains Junie or any other tool that only supports stdio or SSE transport, use this setup.

To connect with a Local MCP Client:

Generate a permanent token for your YouTrack account, selecting YouTrack as the scope. For specific instructions, see Create a Permanent Token.
Add the following reference to the configuration for your AI tool:
{ "mcpServers": { "youtrack": { "command": "npx", "args": [ "mcp-remote", "<your-youtrack-base-URL>/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer <token>" } } } }
- For the <your-youtrack-base-URL>, enter the base URL for your YouTrack site.
- For the <token>, paste the permanent token generated for your YouTrack account.

Alternatively, you can set the value for the authentication header as an environmental variable and use the following command to establish a connection:

npx mcp-remote <your-youtrack-base-URL>/mcp --header Authorization:${AUTH_HEADER}

Set the environmental variable to AUTH_HEADER="Bearer <token>". Replace the <token> placeholder with the permanent token generated for your YouTrack account.
For the <your-youtrack-base-URL>, enter the base URL for your YouTrack site.

AI Tools

YouTrack’s MCP Server includes several built-in tools that help with issues, projects, users, and time tracking. You don’t need to install them — they’re ready to use.

Issue

Issue tools let you search, create, update, and manage issues in YouTrack. They give you direct control over issue data, from creating new tasks and linking related issues to commenting and updating progress.

Name	Description	Sample Prompt
`search_issues`	Searches for issues using YouTrack’s query language. The query can combine attribute filters, keywords, and free text. Returns basic information for matching issues, including the issue ID, summary, project, resolved, reporter, created, updated. For full details, use `get_issue`. The response is paginated using the specified offset and limit.	Find all open bugs assigned to me in the Mobile App project.
`get_issue_fields_schema`	Returns the JSON schema for custom fields in the specified project. Must be used to provide relevant custom fields and values for `create_issue` and `update_issue` actions.	Which fields are required to create issues in the Website Redesign project?
`create_issue`	Creates a new issue in the specified project. Use `get_issue_fields_schema` to discover `customFields` and their possible values for the target project. Important: some fields may be required for issue creation. Returns the ID of the created issue and URL that opens the issue in a web browser. Use get_issue to get the full issue details.	Create a new issue in the Backend API project with the summary "Fix authentication timeout" with a priority of High and assign it to @alex.
`create_draft_issue`	Creates a new issue draft in the specified project. Draft issues are only visible to the current user and can be edited using `update_issue`. Returns the ID assigned to the issue draft and a URL that opens the draft in a web browser.	Start a draft issue in the Marketing Site project with the summary "Revise homepage hero section".
`update_issue`	Updates an existing issue and its fields. Can also be used to star issues and add votes.	Update issue WEB-132 by changing its state to In Progress and adding the label "frontend".
`get_issue`	Returns detailed information for an issue or issue draft, including the summary, description, URL, project, reporter (username), tags, votes, and custom fields. The `customFields` output property provides more important issue details, including Type, State, Assignee, Priority, Subsystem, and so on. Use `get_issue_fields_schema` for the full list of custom fields and their possible values.	Show me all details for issue ID BACK-249.
`change_issue_assignee`	Sets the value for the Assignee field in an issue to the specified user.	Reassign issue DEV-102 to @julia.
`add_issue_comment`	Adds a new comment to the specified issue. Supports Markdown.	Add a comment to issue APP-56: "Great progress. Please include the API documentation before closing."
`get_issue_comments`	Returns a list of issue comments with detailed information for each. The response is paginated using the specified offset and/or limit.	List all comments for issue UX-87.
`get_saved_issue_searches`	Returns saved searches marked as favorites by the current user. The output search queries can be used in `search_issues`. The response is paginated using the specified offset and/or limit.	Show me my saved searches.
`manage_issue_tags`	Adds a tag to or removes a tag from an issue. If a name is used, the first tag that matches the provided name is added. If no matching tags are found, an error message with suggestions for similar tags is returned. When successful, it returns the ID of the updated issue and the updated list of issue tags.	Add the tag "urgent" to issue API-144.
`link_issues`	Links two issues with the specified link type. Returns updated link counts for all target issue link types.	Link issue DOCS-12 to issue DEV-99 as "relates to".

Project

Project tools help you explore and manage projects in YouTrack. Use them to locate projects by name, retrieve detailed configurations, or prepare for actions like creating and drafting issues.

Name	Description	Sample Prompt
`find_projects`	Finds projects whose names contain the specified substring (case-insensitive). Returns minimal information (ID and name) to help pick a project for `get_project`. The response is paginated using the specified offset and/or limit.	Find all projects with "CRM" in the name.
`get_project`	Retrieves full details for a specific project.	Get full details for the "Customer Portal" project.

Group

These tools let you find and inspect user groups or project teams. You can quickly list groups by name or view all members of a specific group to understand how your team is structured.

Name	Description	Sample Prompt
`find_user_groups`	Finds user groups or project teams whose names contain the specified substring (case-insensitive). The response is paginated using the specified offset and/or limit.	List all groups that include the word "Design".
`get_user_group_members`	Lists users who are members of a specified group or project team. Project teams are essentially groups that are always associated with a specific project. The response is paginated using the specified offset and/or limit.	Show me the list of members in the QA Engineers group.

User

User tools provide access to user information within YouTrack. They make it easy to look up a specific user by email or username, or to retrieve details about the currently authenticated account. These tools are particularly valuable for automations or integrations that need to confirm identity, track ownership, or personalize actions based on the current user.

Name	Description	Sample Prompt
`find_user`	Finds users by username or email. Returns profile data for the matching user. This includes the username, full name, email, and local time zone.	Find the user with email alex.rocha@company.com.
`get_current_user`	Returns details about the currently authenticated user (me): username, email, full name, time zone.	Show my account details.

Time Tracking

Time Tracking tools enable you to log and manage work items associated with specific issues. They help teams keep accurate records of time spent on development, testing, or other project activities.

Name	Description	Sample Prompt
`log_work`	Adds a work item (spent time) to the specified issue. You can specify the duration in minutes, optional date, work type, description, and optional work item attributes. Use `get_project` to retrieve the `workTypes` and `workItemAttributesSchema` for the target project.	Log 90 minutes of work on issue DEV-203 with the description "Refactored payment module".

Custom AI Tools

In addition to the predefined AI tools listed here, you can script your own custom AI tools and add them to an app package. Custom tools can be made available to other YouTrack users when they connect to the MCP server from an AI client.

To learn how to build custom AI tools, refer to the documentation in our Developer Portal for YouTrack and Hub.

Optional Parameters

YouTrack's MCP server supports several optional parameters that let you manage how your AI tools interact with your YouTrack site. To set one or more parameters, include the corresponding query parameter in the MCP endpoint URL for your connection.

Parameter	Description
tools	A comma-separated list of tool names that the MCP server will return on a `tools/list` request. For example, `/mcp?tools=search_issues,get_issue`. Use this parameter to help prevent unintentional overuse of your AI quota, especially for expensive requests.
ignoreTools	A comma-separated list of tool names to exclude from the `tools/list` response. For example, `/mcp?ignoreTools=find_user,manage_issue_tags`. Use this parameter to help prevent unintentional overuse of your AI quota, especially for expensive requests.
customToolPackages	A comma-separated list of custom tools that are available to the MCP server. For security reasons, custom tools must be requested specifically by name. For example, `/mcp?customToolPackages=app-name1,app-name2` where `app-name1` and `app-name2` are the names of apps that define custom tools.
enableToolOutputSchema	When `true`, the server returns a JSON Schema which describes the tool output. MCP clients with version 2025-06-18 and above can add this output to the LLM context for tool calling. For example, `/mcp?enableToolOutputSchema=true`. All the predefined AI tools for the YouTrack MCP server return output schemas. Output schemas are also supported in custom tools.

30 October 2025