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 at /mcp/ on the same port as Yamtrack (via nginx + uvicorn). 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:

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

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

Configure your MCP client with the Yamtrack URL and your JWT token:

OpenCode (opencode.json):

{
  "mcpServers": {
    "yamtrack": {
      "transport": "streamable-http",
      "url": "https://your-yamtrack-instance.com/mcp/",
      "headers": {
        "Authorization": "Bearer <your-jwt-token>"
      }
    }
  }
}

Typem / Hermes: same configuration — Streamable HTTP transport pointing to https://your-yamtrack-instance.com/mcp/ with the Authorization header.

Claude Desktop: Claude Desktop only supports stdio transport. If Yamtrack runs in Docker, use docker exec to run the command inside the container:

{
  "mcpServers": {
    "yamtrack": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "yamtrack-app-1",
        "uv",
        "run",
        "python",
        "src/manage.py",
        "run_mcp",
        "--token",
        "<your-jwt-token>"
      ]
    }
  }
}

Replace yamtrack-app-1 with your container name (check with docker ps). Alternatively, set YAMTRACK_JWT as an environment variable on the container and omit --token — the command reads it automatically.

Media Types

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

Status Values

• Completed
• In progress
• Planning
• Paused
• Dropped