yamtrack-mcp

Leer en español

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

It runs on any machine and talks to a 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 for that instance (from Account settings → Integrations)

Related MCP server: Yandex Tracker MCP Server

Install

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

1. Global install from release tarball (recommended)

Download the pre-built tarball from the latest release and install globally:

npm install -g https://github.com/URD0TH/yamtrack-mcp/releases/latest/download/urd0th-yamtrack-mcp-0.1.2.tgz

After this, the yamtrack-mcp command is available everywhere.

Or skip the install and run directly with npx:

npx github:URD0TH/yamtrack-mcp

Security note: pin an explicit version (change 0.1.2 to the tag you want) rather than relying on latest, so a compromised push can't be pulled automatically.

2. GitHub Packages (scoped registry — requires a token)

The Publish workflow pushes @urd0th/yamtrack-mcp to GitHub Packages on each v* tag. GitHub Packages requires authentication even for public packages, so consumers must configure the @urd0th scope and a GitHub token with read:packages before installing:

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

Security note: pin an explicit version (@0.1.0) rather than @latest. Without the .npmrc entries above, npm install -g @urd0th/yamtrack-mcp returns 401.

Build from source

git clone https://github.com/URD0TH/yamtrack-mcp
cd yamtrack-mcp
npm install        # install dependencies
npm run build      # compile src/ -> dist/ (strict TypeScript)

Run

After installing globally (method 1 or 2):

yamtrack-mcp --transport http --port 8080                                # foreground (dev / testing)
yamtrack-mcp --transport http --port 8080 --base-url http://url:port/api # foreground, custom instance
yamtrack-mcp serve --port 9123                                              # daemonized via PM2 (production)
yamtrack-mcp serve --port 9123 --base-url http://url:port/api              # daemonized, custom instance
yamtrack-mcp --transport stdio                 # default, for local stdio clients
yamtrack-mcp serve:status                      # check server status
yamtrack-mcp serve:restart                     # restart
yamtrack-mcp serve:stop                        # stop
yamtrack-mcp serve:logs                        # log file paths
yamtrack-mcp --help                            # show all options

serve vs without serve: Without serve the process runs in the foreground — use it for development, testing, or with your own supervisor (systemd, Docker restart:). With serve the process daemonizes via PM2 with auto-restart and log management (no separate PM2 install required).

With npx (no install):

npx github:URD0TH/yamtrack-mcp --transport http

From source build (Build from source section):

node dist/index.js --transport http

Authentication

The server authenticates to Yamtrack with a single static account API key (from Account settings → Integrations), passed via --token <token> or the YAMTRACK_API_KEY env var. It never expires and is the only credential the server accepts.

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

One token, two ways to pass it. There is a single credential — your Yamtrack account API key. "Bearer" is just how it's sent, not a different token.

• stdio: set the raw key in YAMTRACK_API_KEY (or --token). Do not write Bearer — the server adds the Bearer prefix for you when it calls the REST API.

  "env": { "YAMTRACK_API_KEY": "<token>" }

• http: the client sends Authorization: Bearer <token> and the server forwards that same key. Here you do write Bearer.

  "headers": { "Authorization": "Bearer <token>" }

The <token> value is identical in both cases.

HTTP transport

With --transport http the server listens on POST /mcp (StreamableHTTP, stateless). Each connection authenticates via the Authorization: Bearer <token> header it receives, falling back to --token / YAMTRACK_API_KEY when the header is absent. The token is then forwarded as a Bearer token to the Yamtrack REST API, exactly like the stdio transport.

Security note: the HTTP transport has no built-in TLS or rate limiting. Bind it to localhost and expose it only behind a reverse proxy with HTTPS/authentication — never directly to the internet.

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

If you installed globally (method 1), use "command": "yamtrack-mcp". If you prefer npx (no install), use "command": "npx" with "args": ["github:URD0TH/yamtrack-mcp"].

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "yamtrack": {
      "command": "yamtrack-mcp",
      "env": { "YAMTRACK_API_KEY": "<token>" }
    }
  }
}

OpenCode (opencode.json)

{
  "mcp": {
    "servers": {
      "yamtrack": {
        "type": "stdio",
        "command": "yamtrack-mcp",
        "env": { "YAMTRACK_API_KEY": "<token>" }
      }
    }
  }
}

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

Same command shape; pass the token via the YAMTRACK_API_KEY env var.

HTTP transport (any client that supports url + headers)

Start the server:

yamtrack-mcp serve --port 8080 --base-url http://url:port/api

Then configure the client:

{
  "mcpServers": {
    "yamtrack": {
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

See the wiki MCP for detailed configuration examples for each client.

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, tests/http.test.ts) drive every tool against an in-process mock REST API over InMemoryTransport and HTTP, covering auth (static token, per-request Bearer header, fallback token) and request/response shapes.

Resilience

For stdio, the MCP client respawns the process on exit. For HTTP, use the serve subcommand which runs under PM2 with auto-restart and log management (no separate PM2 install needed).

Alternatively, run yamtrack-mcp --transport http with your own supervisor (systemd, Docker restart:, etc.). A supervise.sh helper is also available in the repo.

Project structure

yamtrack-mcp/
├── src/
│   ├── index.ts     # Entry: transport selection (stdio/http), CLI args
│   ├── client.ts    # YamtrackClient: REST wrapper, Bearer auth
│   └── 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

FAQ

npm install -g github:URD0TH/yamtrack-mcp does not work

This command creates a symlink in the global node_modules pointing to a temporary npm directory that gets deleted after installation, leaving a broken binary. This is a known issue with npm install -g and git dependencies.

Use the release tarball (method 1) or GitHub Packages (method 2) instead.

License

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