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. 8003 if the container publishes 8003:8000), not the MCP port. If omitted it defaults to http://localhost:8000/api.

Example — Yamtrack container on 8003, MCP server on 9123:

node dist/index.js --transport http --port 9123 --base-url http://10.0.0.5:8003/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.

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