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.

Transports

The MCP server supports two transport modes:

Transport	Protocol	Use Case
stdio	stdin/stdout	Local clients (Claude Desktop, OpenCode CLI)
Streamable HTTP	HTTP POST	Remote clients (OpenCode, Typem, Hermes over network)

Both share the same tools and authentication system.

Authentication

• HTTP: Send JWT in Authorization: Bearer <token> header (same token as the REST API)
• stdio: Pass --token=<jwt> flag or set YAMTRACK_JWT environment variable
• 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

Setup

For Local Clients (stdio)

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "yamtrack": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/yamtrack",
        "python",
        "src/manage.py",
        "run_mcp",
        "--token",
        "<your-jwt-token>"
      ]
    }
  }
}

OpenCode (opencode.json):

{
  "mcpServers": {
    "yamtrack": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/yamtrack",
        "python",
        "src/manage.py",
        "run_mcp",
        "--token",
        "<your-jwt-token>"
      ]
    }
  }
}

For Remote Clients (HTTP)

The MCP server is automatically served at /mcp/ on the same nginx port when running with the default Docker setup. Configure your MCP client:

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

To get a JWT token:

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

Media Types

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

Status Values

• Completed
• In progress
• Planning
• Paused
• Dropped