MCP

MCP Server Documentation

Yamtrack includes a Model Context Protocol (MCP) server that exposes media tracking tools for AI assistants like Claude Desktop, OpenCode, Typem, and Hermes.

The MCP server is served over Streamable HTTP at /mcp — uvicorn on port 8002, also proxied by nginx at :8000/mcp/. Authenticate with the same JWT token used for the REST API.

Authentication

Send your JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

To get a token, call the REST API token endpoint with your account credentials:

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

The response contains access and refresh JWTs — use the access token as the bearer token for MCP. Tokens expire; re-run the request when you get auth errors.

Docker / self-hosted (no account handy)

If you run the container and just need a token for an existing user, mint one inside the container. The MCP server and API share the same SECRET, so the token is accepted:

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 Authorization: Bearer <token> header (or the YAMTRACK_JWT env var for stdio).

Read-only tools (search, details) work without authentication.

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

Actions

Tool	Parameters	Description
create_entry	media_id, source, media_type, status, score, progress, notes	Start tracking new media
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)

Statistics

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

Client Configuration

The MCP server speaks Streamable HTTP at http://<host>:8002/mcp (uvicorn) or via nginx at http://<host>:8000/mcp/. Pick the config that matches your client.

When calling the endpoint directly (e.g. with curl), send Accept: application/json, text/event-stream; otherwise nginx returns 406.

OpenCode

OpenCode connects natively over Streamable HTTP. Add under mcp.servers in opencode.json (project root or ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "yamtrack": {
        "type": "remote",
        "url": "http://localhost:8002/mcp",
        "oauth": false,
        "enabled": true,
        "headers": {
          "Authorization": "Bearer <your-jwt-token>"
        }
      }
    }
  }
}

Set "oauth": false so OpenCode uses the static Authorization header instead of attempting OAuth discovery. Interpolate from the environment with "Authorization": "Bearer {env:YAMTRACK_JWT}".

VS Code

Add to .vscode/mcp.json (workspace) or your user profile. VS Code uses the servers key and type: "http" for Streamable HTTP:

{
  "servers": {
    "yamtrack": {
      "type": "http",
      "url": "http://localhost:8002/mcp",
      "headers": {
        "Authorization": "Bearer <your-jwt-token>"
      }
    }
  }
}

VS Code tries Streamable HTTP first and falls back to SSE. Use ${input:yamtrack-token} in the header value to be prompted, or hard-code the token.

Hermes

Hermes reads MCP servers from ~/.hermes/config.yaml under mcp_servers (YAML). Its MCP client speaks both stdio and HTTP, so point it at the HTTP endpoint:

mcp_servers:
  yamtrack:
    url: "http://localhost:8002/mcp"
    headers:
      Authorization: "Bearer <your-jwt-token>"

Claude Desktop

claude_desktop_config.json is stdio-only and silently drops entries that use url / type: "http". For a local HTTP server, bridge it with mcp-remote (Node.js 18+):

{
  "mcpServers": {
    "yamtrack": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8002/mcp", "--transport", "http-only"],
      "env": {
        "MCP_REMOTE_HEADERS": "Authorization: Bearer <your-jwt-token>"
      }
    }
  }
}

The --transport http-only flag skips SSE negotiation. For a remote/self-hosted HTTPS instance, use Settings → Connectors → Add custom connector and paste https://your-yamtrack-instance.com/mcp/ instead (OAuth or API key).

Native stdio (same environment)

If the client runs where Yamtrack's code is available (same host, or inside the container), launch the server directly — no HTTP, no bridge:

YAMTRACK_JWT=<your-jwt-token> uv run python src/manage.py run_mcp
# or inside the container:
docker exec -i yamtrack uv run python src/manage.py run_mcp

Pass the token via the YAMTRACK_JWT env var or the --token argument. Without a token only read-only tools work. Status messages are written to stderr so they don't corrupt the stdio JSON-RPC stream.

Media Types

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

Status Values

• Completed
• In progress
• Planning
• Paused
• Dropped