Module 3, Lesson 8: Connecting Claude Desktop to YouTrack

In this lesson, I'm connecting Claude Desktop to YouTrack — a separate connection from the Claude Code + YouTrack setup we did in Lesson 6. This one's specifically so we can manage non-dev work (GTM, sales, marketing tasks) from Claude Desktop. By the end, we'll have YouTrack connected, tested, and ready to start scoping the GTM project in the next lesson.

Before We Start

Here's what I'd expect you to have under your belt before this lesson:

From previous lessons:

• Your development project board is already set up in YouTrack (Module 3, Lesson 7)
• You've used Claude Desktop before and understand what MCP integrations do — we covered that in Module 2 (Figma) and Module 3, Lesson 1 (JetBrains)
• Claude Code is already connected to YouTrack from Module 3, Lesson 6 — this is a separate connection for Claude Desktop

Tools / setup you'll need:

• Claude Desktop app (the local desktop version — not the web/browser version)
• A text editor for editing JSON files — Sublime Text, VS Code, or even Notepad will do
• Your YouTrack instance URL (e.g. yourusername.youtrack.cloud)
• A YouTrack API token — I'll show you how to create one if you don't have it handy

By the end of this lesson, you'll:

• Know how to manually add an MCP integration to Claude Desktop by editing the config file
• Have YouTrack connected to Claude Desktop and confirmed as working
• Have a second YouTrack project set up for GTM and product management work (separate from the dev project)

About This Lesson

Duration: ~12 minutes video + ~15 minutes to set up on your own machine
Skill Level: Intermediate
What You'll Build: A working YouTrack MCP connection inside Claude Desktop, tested and ready for the GTM scoping session in the next lesson

This lesson is a short but important setup step. We're separating dev work from non-dev work in YouTrack — two projects, two audiences, one tool. Claude Desktop handles the business side; Claude Code handles the build side. Getting this wired up now means the next lesson can move fast.

Watch the Lesson

What We're Covering

Here's what I'm walking you through in this lesson and why it matters:

• Why a separate GTM project — the dev board and the GTM board serve different people; they shouldn't live in the same place
• Setting up the YouTrack project — creating a product management project and making sure the right custom fields are there
• Manually editing the Claude Desktop config — how to add an MCP server by editing claude_desktop_config.json directly
• Replacing your username and token — the two things you actually need to change
• Creating or regenerating your API token — what to do if you can't find the one you made before
• Testing the connection — a quick smoke test to confirm it's actually working before we trust it with real work

1. Let's Set the Scene (~0:00)

We already have our development project in YouTrack — Epics, User Stories, the whole board. That's the technical side of the product. But if you're building something real, there's a whole other stream of work running alongside that: marketing, sales, launch planning, content, GTM campaigns. That stuff deserves to be tracked properly too.

In this lesson, we're going to create a separate YouTrack project specifically for that non-dev work. And then we're going to connect Claude Desktop to YouTrack so it can read and write to that project directly.

If you're planning to hand the dev work off to someone else and focus on the product and go-to-market side yourself — this is the setup you need. Or if you're wearing both hats, you'll want both connections running.

Either way, the dev project stays as-is. We're not touching it. We're adding a second project and a new connection.

2. Create the GTM Project in YouTrack (~0:45)

First, let's create the new project before we touch any config files.

In YouTrack, go to Projects → New Project. For the template, choose Product Management — this is the important bit. When you pick Product Management, YouTrack will automatically set up custom fields for Estimate, Spent Time, and Due Date. You want those. The dev project we created before didn't need them, but for task and milestone tracking on the GTM side, they're useful.

Give your project a name that makes sense for your product. In my case, I named mine after the product with a "GTM" marker to make it obvious what it is. I also gave it a short ID — I used NGTM — because you'll reference that ID in prompts later.

Once it's created, go to Custom Fields and confirm you see Estimate, Spent Time, and Due Date listed. If they're there, you're good to go.

3. Add YouTrack to Claude Desktop (~1:50)

Now for the actual connection. Here's the thing: YouTrack doesn't have a built-in integration option inside Claude Desktop the way some other tools do. So we're adding it manually by editing a JSON config file. It sounds more complicated than it is — you're literally just adding a block of text to a file.

3.1 Open the Config File

In Claude Desktop, click your profile icon (sidebar, top or bottom depending on your version), go to Settings, then Developer. You should see your current MCP integrations listed there — you'll have Filesystem at minimum, and if you've been following along, JetBrains should be there too.

Click Edit Config. This will open your file manager and navigate you to the folder containing claude_desktop_config.json. Double-click that file to open it in a text editor. If nothing opens it automatically, right-click and choose to open it with VS Code, Sublime Text, or Notepad — whichever you have.

3.2 Understand the File Structure

When you open it, you'll see JSON — curly braces, key-value pairs, indentation. Don't worry if it looks foreign. You don't need to understand all of it. The structure looks roughly like this:

{
  "mcpServers": {
    "jetbrains": {
      ...existing config...
    }
  }
}

Each MCP integration is a named block inside "mcpServers". We're going to add a new block for YouTrack alongside the existing ones.

3.3 Add the YouTrack Block

Find the closing } of the last existing server entry. After it (but still inside "mcpServers"), add a comma, then paste the YouTrack config block.

The config I use is in the Quick Reference section at the bottom — copy it from there. Once you've pasted it, there are exactly two things to replace:

1. <username> — replace with your YouTrack subdomain. If your YouTrack URL is deletosh.youtrack.cloud, your username is deletosh.
2. <token> — replace with your API token (covered in the next step).

That's it. Everything else in that block stays exactly as-is.

4. Get Your YouTrack API Token (~5:30)

The token is how YouTrack knows that Claude Desktop is allowed to read and write to your account. If you created one during the Claude Code + YouTrack setup in Module 3, Lesson 6, you can reuse that one — just paste it in.

If you don't have it handy (or you'd rather create a fresh one for Claude Desktop specifically), here's how:

1. In YouTrack, click your profile avatar (top right)
2. Go to Account Security
3. Scroll to Tokens — you'll see any you've already created
4. Click New Token, give it a name (I called mine "Claude Desktop"), and click Create
5. Copy the token immediately — you won't be able to see it again after you close that modal

Once you have it, go back to your text editor and replace <token> in the config file with the token you just copied.

5. Save, Quit, and Restart Claude Desktop (~6:30)

Once you've made your edits, save the file — Cmd+S on Mac, Ctrl+S on Windows.

Now you need to fully quit Claude Desktop — not just close the window, but quit the application entirely. On Mac: right-click the dock icon → Quit. On Windows: right-click the taskbar icon → Exit. Then reopen it.

This matters. Claude Desktop reads the config file on startup. If you don't restart it, it won't pick up the new integration.

Once it's back open, go to Settings → Developer again and look for YouTrack in the list. If you see it and it shows as running, the connection is live.

6. Test the Connection (~7:20)

Don't trust the green indicator alone. Let's actually test that it can read and write.

Open a new chat in Claude Desktop. Type something like:

Using the YouTrack tool, show me the issues in my [YOUR-PROJECT-ID] project.

Replace [YOUR-PROJECT-ID] with the short ID you gave your GTM project (I used NGTM).

Claude Desktop will ask if it can use the YouTrack tool — click Allow. If all is well, it'll come back with something like "the project has no issues." That's fine — we haven't added any yet. The point is it found the project and got a response without an error.

If you want a more definitive test, ask it to create a sample issue in the project:

Create a sample issue in my [YOUR-PROJECT-ID] project.

Allow it to use the tool again. Then go to YouTrack, open your GTM project, and refresh the page. You should see a draft issue sitting there. That's your confirmation it's working end to end.

7. Why Claude Desktop Here, Not Claude Code?

I want to briefly explain the split, because it might not be obvious.

Claude Code is your development tool. It lives in your terminal, it has access to your project files, and it's optimised for writing and editing code. That's why we used it to build the dev board in YouTrack — it can read your spec files, cross-reference your roadmap, and write technically precise issues.

Claude Desktop is your general-purpose tool. It's connected to Obsidian, Figma, and now YouTrack — but it's not sitting inside your codebase. For GTM and product management tasks, that's actually what you want. You're not writing implementation tickets. You're writing campaign tasks, launch milestones, sales outreach plans. Claude Desktop, with access to all your product documents via Obsidian, is better suited for that.

The two connections — Claude Code → YouTrack and Claude Desktop → YouTrack — can coexist. They both use the same YouTrack instance; they just live in different tools and serve different workflows.

8. You Should Be Able to Build This Now

Here's what you can put together with what we just covered:

• A working YouTrack MCP integration in Claude Desktop, installed manually via the config file
• A separate GTM/product management project in YouTrack, ready to receive tasks from the next lesson

Check Yourself

• I've created a Product Management project in YouTrack (with Estimate, Spent Time, and Due Date fields)
• I've edited claude_desktop_config.json and added the YouTrack MCP block
• I've restarted Claude Desktop and see YouTrack listed as "running" in Developer settings
• I've tested it by creating or listing an issue and confirmed it worked

If Something's Not Working

The Short Version

Here's what I want you to walk away with:

• Claude Desktop ≠ Claude Code. Two separate tools. Both can connect to YouTrack, but for different workflows. Desktop for GTM and product tasks; Code for dev.
• The config file is just JSON. Editing it manually sounds scary but it's just adding one block of text. Two values to replace: your username and your token.
• Always fully quit and relaunch. Claude Desktop reads config on startup. Closing the window isn't enough.
• What you can do now: In the next lesson, we're using this connection to scope the entire GTM project in YouTrack — same approach we used for the dev board, just focused on the go-to-market side.

Quick Reference

The MCP Config Block

Add this inside the "mcpServers" object in your claude_desktop_config.json. Replace <username> with your YouTrack subdomain and <token> with your API token:

"youtrack-prt": {
  "command": "npx",
  "args": [
    "mcp-remote",
    "https://<username>.youtrack.cloud/mcp",
    "--header",
    "Authorization:${AUTH_HEADER}"
  ],
  "env": {
    "AUTH_HEADER": "Bearer <token>"
  }
}

What Your Full Config Should Look Like

Your mcpServers block should look something like this after adding YouTrack (your existing entries will differ):

{
  "mcpServers": {
    "filesystem": {
      ...
    },
    "jetbrains": {
      ...
    },
    "youtrack-prt": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<username>.youtrack.cloud/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <token>"
      }
    }
  }
}

Each server entry needs to be separated by a comma. The last entry before the closing } of mcpServers should not have a trailing comma.

Where to Find the Config File

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

The easiest way to get there is via Claude Desktop → Settings → Developer → Edit Config.

How to Create a YouTrack API Token

1. Profile avatar → Account Security
2. Scroll to Tokens
3. Click New Token → name it (e.g. "Claude Desktop") → Create
4. Copy the token immediately — it won't be shown again

Quick Smoke Test

Once connected, paste this in a new Claude Desktop chat:

Using the YouTrack tool, show me the issues in my [YOUR-PROJECT-ID] project.

If it responds (even to say the project is empty) — you're connected.

Resources

Links & Docs

• YouTrack API Tokens documentation — how to create and manage permanent tokens
• Claude Desktop MCP configuration guide — general reference for adding MCP servers to Claude Desktop

Tools Used

• YouTrack — free tier available
• Claude Desktop — local desktop app (not the browser version)
• Sublime Text or VS Code — for editing the JSON config file

Questions I Get Asked

Q: I already connected Claude Code to YouTrack in Lesson 6 — do I really need to do this again?

Yes, because they're completely separate connections. Claude Code connects via its own config inside WebStorm. Claude Desktop connects via its own JSON config file. They both talk to the same YouTrack instance, but from different tools. You need both set up if you want to use YouTrack from both places.

Q: Can I use the same API token for both Claude Code and Claude Desktop?

You can, but I prefer to create separate tokens so I can revoke one without affecting the other. It also makes it easier to see in YouTrack's Account Security which tool is doing what.

Q: What's mcp-remote? Do I need to install it?

mcp-remote is an npm package that handles the remote MCP connection. The config uses npx to run it, which means npm downloads and runs it automatically the first time — you don't need to install anything separately. As long as Node.js is installed on your machine, this works.

Q: Why is the MCP key named youtrack-prt in the config?

That's just the name I gave it. You can name it whatever you like — it's just an identifier inside the config file. I used prt as a shorthand for my project. The name doesn't affect how it functions.

Q: How do I know I'm ready for the next lesson?

You have YouTrack showing as "running" in Claude Desktop settings, and your smoke test (asking it to list or create an issue) worked. That's all you need.

💬 Stuck? Come Talk to Us

Glossary

MCP (Model Context Protocol): The protocol that lets Claude connect to external tools and services. When we add an MCP server to Claude Desktop, we're giving Claude the ability to read and write to that tool directly from a chat window. (first came up in Module 2, Lesson 4 with the Figma integration)

claude_desktop_config.json: The configuration file that tells Claude Desktop which MCP servers to load when it starts. Lives in the Claude application data folder. You edit it directly with any text editor to add new integrations. (first came up in this lesson)

API Token: A secret key that authorises Claude to act on your behalf in YouTrack. It's tied to your account and grants whatever permissions your account has. Keep it private — anyone with your token can access your YouTrack. (first came up in Module 3, Lesson 6 with the Claude Code + YouTrack setup)

mcp-remote: An npm package that Claude Desktop uses to connect to remote MCP servers over the internet. Runs automatically via npx — you don't install it yourself. (first came up in this lesson)

Product Management template (YouTrack): A project template in YouTrack that pre-configures fields like Estimate, Spent Time, and Due Date. Better suited for GTM and operational tasks than the default project template, which is more lightweight. (first came up in this lesson)