MCP

MCP Server Documentation

Yamtrack has a standalone Model Context Protocol (MCP) server, yamtrack-mcp, that exposes media tracking tools for AI assistants like Claude Desktop, OpenCode, VS Code, and Hermes.

It is a TypeScript stdio server that talks to any Yamtrack instance over the public REST API, so it needs no Django, no Python, and no HTTP bridge — just Node.js 18+. It is also vendored as the mcp/ git submodule in the main repo.

git clone https://github.com/URD0TH/yamtrack-mcp
cd yamtrack-mcp
npm install
npm run build
node dist/index.js --help

Authentication

The server authenticates to Yamtrack with a Bearer token. Auth precedence: --token / YAMTRACK_JWT, else --username + --password (mints a JWT and auto-refreshes it on expiry). Read-only tools (search_media, get_details) work without a token.

Static API token (recommended)

Each user has a static API token — the same one shown (with a copy button) and regenerable from Account settings → Integrations. It is short, never expires, and is the recommended token: set it once and you never have to refresh it. Pass it via --token or the YAMTRACK_JWT env var.

This token also authorizes integration webhooks (Plex/Jellyfin/Emby), so treat it like any other API key.

JWT (REST API token)

You can also use a JWT from the REST API token endpoint. It expires after one hour, so re-run to get a fresh access token when you see auth errors:

curl -X POST https://your-yamtrack-instance.com/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username":"your-username","password":"your-password"}'

Use the returned access token via --token or the YAMTRACK_JWT env var. Alternatively, pass --username + --password and let the server mint and auto-refresh the JWT for you.

Docker / self-hosted (no account handy)

If you run the container and just need a token for an existing user, mint a JWT inside the container:

docker exec -i yamtrack uv run python -c "
from rest_framework_simplejwt.tokens import AccessToken
from django.contrib.auth import get_user_model
u = get_user_model().objects.first()  # or .get(username='...')
print(str(AccessToken.for_user(u)))
"

Copy the printed token into the YAMTRACK_JWT env var or the --token argument.

Tools

Search & Browse

Tool	Parameters	Description
search_media	query, media_type, page, source	Search external providers for media
get_details	source, media_type, media_id, season_number	Get metadata from a provider

Tracked Media

Tool	Parameters	Description
list_tracked_media	media_type, status, sort, search	List user's tracked media
get_home	sort	Dashboard with in-progress and planning items
get_history	source, media_type, media_id, season_number, episode_number	Change history for an item
get_me	–	Current authenticated user

Actions

Tool	Parameters	Description
create_entry	media_id, source, media_type, status, score, progress, notes	Start tracking new media
manual_create	–	Create a custom/manual entry
update_entry	media_type, instance_id, status, score, progress, notes	Update tracked media
update_progress	media_type, instance_id, operation	Increase or decrease progress
update_score	media_type, instance_id, score	Update score (0-10)
delete_entry	media_type, instance_id	Stop tracking an item

Statistics

Tool	Parameters	Description
get_statistics	start_date, end_date	Aggregated stats and activity data

Client Configuration

The server speaks stdio, so configure it with command/args pointing at the built dist/index.js. Pass the token via the YAMTRACK_JWT env var and the instance URL via YAMTRACK_BASE_URL (default http://localhost:8000/api).

Claude Desktop

{
  "mcpServers": {
    "yamtrack": {
      "command": "node",
      "args": ["/abs/path/to/yamtrack-mcp/dist/index.js"],
      "env": {
        "YAMTRACK_JWT": "<your-token>",
        "YAMTRACK_BASE_URL": "https://your-yamtrack-instance.com/api"
      }
    }
  }
}

OpenCode

Add under mcp.servers in opencode.json (project root or ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "yamtrack": {
        "type": "stdio",
        "command": "node",
        "args": ["/abs/path/to/yamtrack-mcp/dist/index.js"],
        "enabled": true,
        "env": {
          "YAMTRACK_JWT": "<your-token>",
          "YAMTRACK_BASE_URL": "https://your-yamtrack-instance.com/api"
        }
      }
    }
  }
}

VS Code / Hermes

Use the same command/args shape and pass the token via the YAMTRACK_JWT env var. VS Code reads .vscode/mcp.json (workspace) or your user profile; Hermes reads ~/.hermes/config.yaml under mcp_servers.

Media Types

Supported media types for tools: tv, movie, anime, manga, game, book, comic, boardgame.

Status Values

• Completed
• In progress
• Planning
• Paused
• Dropped