Skip to content

MCP

Jump to bottom
bnds edited this page Jul 15, 2026 · 19 revisions

MCP Server Documentation

Yamtrack has a standalone Model Context Protocol (MCP) server, yamtrack-mcp, that exposes media tracking tools for AI assistants like Claude Desktop, OpenCode, VS Code, and Hermes.

It is a TypeScript stdio (or http) server that talks to any Yamtrack instance over the public REST API, so it needs no Django, no Python, and no HTTP bridge — just Node.js 18+. It is also vendored as the mcp/ git submodule in the main repo.

git clone https://github.com/URD0TH/yamtrack-mcp
cd yamtrack-mcp
npm install
npm run build
node dist/index.js --help

Authentication

The server authenticates to Yamtrack with a single static API key. Read-only tools (search_media, get_details) work without a token.

Static API key (only method)

Each user has a static API key — the same token shown (with a copy button) and regenerable from Account settings → Integrations. It never expires and is the only credential the server accepts. It also authorizes the REST API and integration webhooks (Plex/Jellyfin/Emby), so the same key works for the MCP server, the API, and webhooks.

How the key reaches the server depends on the transport:

  • stdio (default): pass it via --token or the YAMTRACK_API_KEY env var.
  • http (--transport http): send it as the Authorization: Bearer <key> header on each connection. If the header is absent, the server falls back to --token / YAMTRACK_API_KEY.

In both cases the server forwards the key as Authorization: Bearer <key> to the Yamtrack REST API.

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
get_me – Current authenticated user

Actions

Tool Parameters Description
create_entry media_id, source, media_type, status, score, progress, notes Start tracking new media
manual_create – Create a custom/manual entry
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)
delete_entry media_type, instance_id Stop tracking an item

Statistics

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

Client Configuration

The server speaks stdio, so configure it with command/args pointing at the built dist/index.js. Pass the token via the YAMTRACK_API_KEY env var and the instance URL via YAMTRACK_BASE_URL (default http://localhost:8000/api).

Claude Desktop

{
  "mcpServers": {
    "yamtrack": {
      "command": "node",
      "args": ["/abs/path/to/yamtrack-mcp/dist/index.js"],
      "env": {
        "YAMTRACK_API_KEY": "<your-token>",
        "YAMTRACK_BASE_URL": "https://your-yamtrack-instance.com/api"
      }
    }
  }
}

OpenCode

Add under mcp.servers in opencode.json (project root or ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "yamtrack": {
        "type": "stdio",
        "command": "node",
        "args": ["/abs/path/to/yamtrack-mcp/dist/index.js"],
        "enabled": true,
        "env": {
          "YAMTRACK_API_KEY": "<your-token>",
          "YAMTRACK_BASE_URL": "https://your-yamtrack-instance.com/api"
        }
      }
    }
  }
}

VS Code / Hermes

Use the same command/args shape and pass the token via the YAMTRACK_API_KEY env var. VS Code reads .vscode/mcp.json (workspace) or your user profile; Hermes reads ~/.hermes/config.yaml under mcp_servers.

HTTP transport (any client that supports url + headers)

Run the server with node dist/index.js --transport http (optionally --port <n>, default 8080). It listens on POST /mcp (StreamableHTTP, stateless) and authenticates each connection via the Authorization: Bearer <key> header. This mirrors how other HTTP MCP servers (e.g. Simkl) are configured.

Two ports, two endpoints — do not swap them

The MCP server sits between your assistant and Yamtrack, so it binds two different addresses that are easy to confuse:

Flag Endpoint What it is Who connects there
--port <n> http://<host>:<n>/mcp The MCP server itself (this program) Your assistant (Claude, Hermes, etc.)
--base-url <url> http://<host>:<api-port>/api The Yamtrack REST API (Django) The MCP server (as an HTTP client)
  • --port / /mcp is where the assistant connects. Pick any free port (e.g. 9123).
  • --base-url / /api is where Yamtrack runs. This is the API port of your Yamtrack instance (e.g. 8000, the port the Yamtrack container publishes), not the MCP port. If omitted it defaults to http://localhost:8000/api.

Example — Yamtrack on 8000, MCP server on 9123:

node dist/index.js --transport http --port 9123 --base-url http://10.0.0.5:8000/api
{
  "mcpServers": {
    "yamtrack": {
      "url": "http://10.0.0.5:9123/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

The /mcp endpoint is provided only by this standalone server — Yamtrack itself has no /mcp route.

Keeping it alive

The bundled supervise.sh restarts the server if it crashes, up to YAMTRACK_MCP_MAX_RETRIES attempts (default 5, YAMTRACK_MCP_RETRY_INTERVAL seconds between tries, default 2). Every attempt and the final give-up are logged to stderr; after the limit it exits. A clean exit (code 0) is not retried.

./supervise.sh --transport http --port 9123 --base-url http://10.0.0.5:8000/api

Media Types

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

Status Values

  • Completed
  • In progress
  • Planning
  • Paused
  • Dropped

Clone this wiki locally