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 '{"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

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 — it cannot connect directly to HTTP MCP servers. Use a stdio-to-HTTP bridge like mcp-remote:

npx mcp-remote https://your-yamtrack-instance.com/mcp/

Configure in claude_desktop_config.json:

{
  "mcpServers": {
    "yamtrack": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-yamtrack-instance.com/mcp/"
      ],
      "env": {
        "MCP_REMOTE_HEADERS": "Authorization: Bearer <your-jwt-token>"
      }
    }
  }
}

Requires Node.js 18+ and npx (comes with Node). The bridge runs as a local process that forwards JSON-RPC between Claude Desktop (stdio) and your remote Yamtrack instance (Streamable HTTP).

Alternatively, use vikstra-bridge for a standalone binary that doesn't require Node:

{
  "mcpServers": {
    "yamtrack": {
      "command": "vikstra-bridge",
      "args": [
        "https://your-yamtrack-instance.com/mcp/",
        "-header", "Authorization: Bearer <your-jwt-token>"
      ]
    }
  }
}

Media Types

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

Status Values

• Completed
• In progress
• Planning
• Paused
• Dropped