Content
<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](https://modelcontextprotocol.io) 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](docs/INTRODUCTION.md) — the one-page pitch ·
> [docs/INSTALL.md](docs/INSTALL.md) — install & connect in ~10 min ·
> [skills/README.md](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](FINE_TUNED_FEATURES.md)** for the full list, and
**[BLOCKED_OPERATIONS.md](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
```python
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)
```python
# 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
```python
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
```python
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.
```bash
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):
```bash
export YOUTRACK_URL="https://your-instance.youtrack.cloud"
export YOUTRACK_API_TOKEN="perm-XXXXXXXX..."
```
Then run it:
```bash
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`:
```json
{
"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.
```bash
export ENABLED_TOOLS="get_issue,search_issues,update_issue_state" # allowlist
export DISABLED_TOOLS="delete_issue,delete_attachment" # denylist
```
## 🧪 Development
```bash
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](https://github.com/jasonsteinman/youtrack-mcp/issues)
or reach me at **maintainer@example.com**.
---
<sub>Forked from [`tonyzorin/youtrack-mcp`](https://github.com/tonyzorin/youtrack-mcp) and fine-tuned. Thanks to the original author for the foundation.</sub>
