Skip to content

MCP

Jump to bottom
URD0TH 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 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 passed via --token or the YAMTRACK_API_KEY env var. 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.

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.

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