<div align="center">

<img src="assets/header.jpg" alt="Jason-MCP" width="340">

Jason-MCP

A well-functioning YouTrack MCP for people who hate doing YouTrack busywork.

Sprints, squad reports, name-aware actions, and the notifications inbox the official one forgot.

</div>

---

Jason-MCP is a Model Context Protocol server that lets Claude (and any MCP client) drive JetBrains YouTrack — read and write issues, move sprints, report story points per developer/squad, assign people by name, and check what's waiting on you. It speaks plain strings, not fragile API objects, so the common operations just work.

New here / setting it up for a teammate? → docs/INTRODUCTION.md — the one-page pitch · docs/INSTALL.md — install & connect in ~10 min · skills/README.md — the one-word skills pack.

✨ What's fine-tuned here

Beyond the standard YouTrack tools, Jason-MCP adds:

• 🗂️ Schema-aware custom fields — field types are read from the issue itself, so any State/enum/user field updates correctly (no more StateBundleElement type errors), and fields can actually be cleared (unassign everyone in one call).
• 🏃 Sprint operations — move issues between sprints, roll sprints over, fetch sprint contents.
• 📊 Team reporting — story points per developer and per squad.
• 🙋 Name-aware actions — assign, set reviewer, and @-mention people by display name, not just login. Jason-MCP resolves the name for you.
• 🔔 Notifications inbox — surface mentions and comment activity the official MCP doesn't expose.

See FINE_TUNED_FEATURES.md for the full list, and BLOCKED_OPERATIONS.md for the custom-field fixes and why they were needed.

🚀 Quick reference — common operations

These use the proven simple-string format. Pass plain strings, not nested objects.

State, priority, assignee, type, estimation

update_issue_state("DEMO-123", "In Progress")
update_issue_priority("DEMO-123", "Critical")
update_issue_assignee("DEMO-123", "john.doe")     # or a display name: "John Doe"
update_issue_type("DEMO-123", "Bug")
update_issue_estimation("DEMO-123", "4h")          # 30m · 4h · 2d · 1w · "3d 5h"

Custom fields (and clearing them)

# Set several at once
update_custom_fields("DEMO-123", {"Priority": "Critical", "Type": "Bug"})

# Clear fields — None empties them (unassign everyone, blank the squad, etc.)
update_custom_fields("DEMO-123", {
    "Assignee": None,
    "Reviewer": None,
    "Squad": None,
})
update_issue_assignee("DEMO-123", "unassigned")    # also clears the assignee

Finding, creating, linking, commenting

search_issues("bug in login")
get_project_issues("DEMO")
get_issue("DEMO-123")

create_issue(project_id="DEMO", summary="Bug in login system",
             description="Users cannot log in with special characters")

add_dependency("DEMO-123", "DEMO-124")
add_relates_link("DEMO-123", "DEMO-125")

add_comment("DEMO-123", "Fixed the login bug")
get_issue_comments("DEMO-123")

Attachments

get_issue_raw("DEMO-123")                          # raw data incl. attachments
get_attachment_content("DEMO-123", "1-456")        # download as base64
delete_attachment("DEMO-123", "1-456")             # needs permission

🛠️ Install & run (from source)

Jason-MCP runs straight from this repo over stdio — no Docker or npm package required.

git clone https://github.com/jasonsteinman/youtrack-mcp.git
cd youtrack-mcp

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Set your credentials (or put them in a .env file — it's auto-loaded):

export YOUTRACK_URL="https://your-instance.youtrack.cloud"
export YOUTRACK_API_TOKEN="perm-XXXXXXXX..."

Then run it:

python main.py                     # stdio (default, for MCP clients)
python main.py --transport sse --port 8000   # or SSE over HTTP
python main.py --version

Wire it into Claude

Add Jason-MCP to your MCP client config (e.g. Claude Desktop / Claude Code), pointing at this repo's main.py:

{
  "mcpServers": {
    "youtrack": {
      "command": "python",
      "args": ["/absolute/path/to/youtrack-mcp/main.py"],
      "env": {
        "YOUTRACK_URL": "https://your-instance.youtrack.cloud",
        "YOUTRACK_API_TOKEN": "perm-XXXXXXXX..."
      }
    }
  }
}

⚙️ Configuration

Variable	Purpose
YOUTRACK_URL	Your YouTrack instance URL
YOUTRACK_API_TOKEN	Your YouTrack permanent API token
YOUTRACK_VERIFY_SSL	SSL verification (default: true)
ENABLED_TOOLS	Allowlist — enable only these tools (disables all others)
DISABLED_TOOLS	Denylist — disable specific tools

Tool filtering keeps context lean. Tool names are case-insensitive and treat -/_ the same; ENABLED_TOOLS wins over DISABLED_TOOLS. Filtering happens at startup.

export ENABLED_TOOLS="get_issue,search_issues,update_issue_state"   # allowlist
export DISABLED_TOOLS="delete_issue,delete_attachment"              # denylist

🧪 Development

pip install -r requirements.txt
python -m pytest tests/unit -q          # run the unit suite

The custom-field fixes are covered by tests/unit/test_custom_field_schema_aware.py.

🐱 About the name

Jason-MCP. The kittens are just here for morale.

💬 Support

Questions, bugs, or ideas? Open an issue or reach me at maintainer@example.com.

---

_{Forked from tonyzorin/youtrack-mcp and fine-tuned. Thanks to the original author for the foundation.}