yamtrack-mcp

A standalone Model Context Protocol server (stdio transport, TypeScript) that exposes the Yamtrack REST API as tools for LLMs (Claude Desktop, OpenCode, VS Code, Hermes, etc.).

Unlike the in-repo Python server (src/manage.py run_mcp, HTTP only), this one runs on any machine and talks to a remote Yamtrack instance over its public REST API. No Django code required.

Requirements

• Node.js 18+ (developed on v22/v26)

• A reachable Yamtrack instance (e.g. http://localhost:8000 or your hosted URL)

• An API token or a username/password for that instance

Related MCP server: Yandex Tracker MCP Server

Install & build

npm install        # install dependencies
npm run build      # compile src/ -> dist/ (strict TypeScript)

Run

node dist/index.js --help

Authentication

The server authenticates to Yamtrack with a Bearer token. Precedence:

1. --token <token> / env YAMTRACK_JWT — a static account API token (recommended, never expires) or a JWT.

2. --username + --password — mints a JWT at startup and auto-refreshes it on 401 (JWTs expire after 1h).

Read-only tools (search_media, get_details) work without authentication.

Tools

All tools map 1:1 to the REST API documented in wiki/API.md.

Enum values: media_type ∈ {tv, movie, anime, manga, game, book, comic, boardgame, season}, status ∈ {Completed, In progress, Planning, Paused, Dropped}, source ∈ {tmdb, mal, igdb, openlibrary, mangaupdates, comicvine, custom}.

Client configuration

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "yamtrack": {
      "command": "node",
      "args": ["/abs/path/to/yamtrack-mcp/dist/index.js"],
      "env": { "YAMTRACK_JWT": "<token>" }
    }
  }
}

OpenCode (opencode.json)

{
  "mcp": {
    "servers": {
      "yamtrack": {
        "type": "stdio",
        "command": "node",
        "args": ["/abs/path/to/yamtrack-mcp/dist/index.js"],
        "env": { "YAMTRACK_JWT": "<token>" }
      }
    }
  }
}

VS Code (.vscode/mcp.json) / Hermes (~/.hermes/config.yaml)

Same command/args shape; pass the token via the YAMTRACK_JWT env var.

Development

npm run verify   # typecheck (tsc) + lint/format (biome) + tests (vitest)
npm run typecheck
npm run lint     # biome check .
npm run format   # biome format --write .
npm run test     # vitest run
npm run dev      # build + run

Integration tests (tests/server.test.ts) drive every tool against an in-process mock REST API over InMemoryTransport, covering auth (static token, JWT login, JWT auto-refresh on 401) and request/response shapes.

Project structure

yamtrack-mcp/
├── src/
│   ├── index.ts     # Entry: McpServer + StdioServerTransport, CLI args
│   ├── client.ts    # YamtrackClient: REST wrapper, Bearer auth, JWT refresh
│   └── tools.ts     # Tool definitions mapped to REST endpoints (zod schemas)
├── tests/           # Integration tests with a mock REST API
├── biome.json       # Lint + format config
├── tsconfig*.json   # TypeScript (build + typecheck)
└── vitest.config.ts

License

Part of the Yamtrack project. See the main repository license.