Skip to content

MCP

Jump to bottom
URD0TH edited this page Jul 19, 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.

Install

Distributed via GitHub only — it is not published to npmjs.com, so npx yamtrack-mcp (the public unscoped name) will not work.

Global install from git (recommended — no registry, no auth)

npm install -g github:URD0TH/yamtrack-mcp

After this, the yamtrack-mcp command is available everywhere. Compiles TypeScript on install, runs instantly on every launch.

npx (no install — good for testing)

npx github:URD0TH/yamtrack-mcp

Runs the package on the fly. Compiles TypeScript on every launch (slower startup).

GitHub Packages (scoped registry — requires a token)

echo "@urd0th:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=<GITHUB_TOKEN>" >> ~/.npmrc
npm install -g @urd0th/yamtrack-mcp

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.

Run

After installing globally:

yamtrack-mcp --transport stdio   # default, for local stdio clients
yamtrack-mcp --transport http    # starts HTTP server on :8080/mcp
yamtrack-mcp --help              # show all options

From source build:

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

Options

Flag Default Description
--transport <type> stdio Transport: stdio or http
--base-url <url> http://localhost:8000/api Yamtrack API base URL (also YAMTRACK_BASE_URL env)
--token <key> YAMTRACK_API_KEY env Static API key from Account settings → Integrations
--port <n> 8080 Port for http transport
--help – Show usage and exit

Examples

# Local dev (set YAMTRACK_API_KEY in .bashrc/.env)
export YAMTRACK_API_KEY="your-api-key"
yamtrack-mcp --transport stdio

# HTTP on a custom port, remote instance
yamtrack-mcp --transport http --port 9123 --base-url "http://192.168.1.50:8000/api"

# HTTP with per-connection Bearer auth (no server-side token needed)
yamtrack-mcp --transport http --port 9123

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_date, end_date Start tracking new media
manual_create – Create a custom/manual entry
update_entry media_type, instance_id, status, score, progress, notes, start_date, end_date 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
create_episode media_id, source, season_number, episode_number, end_date Mark an episode as watched (re-send with end_date to correct the watch date)

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 pointing at the installed binary. Pass the token via the YAMTRACK_API_KEY env var and the instance URL via YAMTRACK_BASE_URL (default http://localhost:8000/api).

Note: These configs assume a global install (npm install -g github:URD0TH/yamtrack-mcp). If you built from source, use "command": "node" with "args": ["/path/to/yamtrack-mcp/dist/index.js"] instead.

Claude Desktop

{
  "mcpServers": {
    "yamtrack": {
      "command": "yamtrack-mcp",
      "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": "yamtrack-mcp",
        "enabled": true,
        "env": {
          "YAMTRACK_API_KEY": "<your-token>",
          "YAMTRACK_BASE_URL": "https://your-yamtrack-instance.com/api"
        }
      }
    }
  }
}

VS Code / Hermes

Use the same command 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 yamtrack-mcp --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:

yamtrack-mcp --transport http --port 9123 --base-url http://localhost:8000/api
{
  "mcpServers": {
    "yamtrack": {
      "url": "http://localhost: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

supervise.sh is bundled in the repo root (mcp/supervise.sh) and in the installed package.

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://localhost: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