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:

curl -X POST https://your-yamtrack-instance.com/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username":"your-username","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

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

Streamable HTTP (OpenCode and HTTP-capable clients)

OpenCode connects natively over Streamable HTTP — no bridge needed:

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

For a remote/self-hosted instance use https://your-yamtrack-instance.com/mcp/. When calling the endpoint directly (e.g. with curl), include Accept: application/json, text/event-stream; otherwise nginx returns 406.

stdio bridge via mcp-remote (Claude Desktop, stdio-only clients)

Claude Desktop only supports stdio, so bridge it with mcp-remote (requires Node.js 18+):

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

Native stdio (same environment)

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

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