backloggd-mcp

An MCP server for Backloggd, the video game tracker. It lets an AI assistant search the game catalogue and read and manage your library — statuses, ratings, logs, play sessions, reviews and lists — as the signed-in you.

Beyond plain CRUD it exposes the parts of Backloggd that make it a backlog tool: filtering your library by release platform, genre or year, sorting by how long games take to finish, browsing a studio's whole catalogue with your own status attached, and checking a pile of titles against your shelves and lists in one call.

Backloggd has no public API, so this drives the same endpoints the website's own front end uses. See Automation posture for what that means and how this server tries to be a good citizen about it.

Unofficial. Not affiliated with or endorsed by Backloggd.

Install

Nothing to install — point your MCP client at npx:

Requires Node 20+. Not on npm yet, so install straight from GitHub — the package builds itself on install via its prepare script.

Claude Code — claude mcp add picks up your shell environment, so this is enough:

claude mcp add backloggd -s user -e BACKLOGGD_BROWSER_IMPORT=firefox -- npx -y github:DenisionSoft/backloggd-mcp

Claude Desktop — edit claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS):

{
  "mcpServers": {
    "backloggd": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "github:DenisionSoft/backloggd-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "BACKLOGGD_BROWSER_IMPORT": "firefox"
      }
    }
  }
}

The absolute command path and the explicit PATH are both required, and this is the single most common reason a Desktop MCP server silently fails to start: Desktop is a GUI app and does not inherit your shell environment, so a bare "command": "npx" cannot be found, and even an absolute npx dies with env: node: No such file or directory because its shebang cannot locate node. Adjust the paths if node lives somewhere other than Homebrew (which node will tell you). git must be reachable too — npx clones the repo to install it.

Pinning to a local checkout instead

Installing from a git ref re-resolves against GitHub on every server start (~2s warm, and it blocks rather than falling back to cache if GitHub is unreachable). If you would rather have an instant, offline-capable start — or you are actively editing the code — clone it and point at the build:

git clone https://github.com/DenisionSoft/backloggd-mcp && cd backloggd-mcp && npm install

then use "command": "node", "args": ["/absolute/path/to/backloggd-mcp/dist/index.js"]. That starts in ~250ms and needs no network to launch, but it runs whatever is in dist/ — you must npm run build to pick up changes.

Authentication

Pick one. They are resolved in this order.

Method	Env vars	Notes
Session cookie	BACKLOGGD_SESSION	The _backloggd_session value from your browser's DevTools. No password ever reaches this server. Stops working when the session expires.
Username + password	BACKLOGGD_USERNAME, BACKLOGGD_PASSWORD	The durable option — the server renews the session itself when it lapses.
Import from browser	BACKLOGGD_BROWSER_IMPORT=firefox	Lifts the live session straight out of your local Firefox profile. Best for a local-only setup. Chrome is not supported: its cookie store is encrypted with an OS-keychain key that this server deliberately does not touch.

The resolved session is cached in ~/.backloggd-mcp/session.json (mode 0600) so restarts do not re-authenticate. The cache is keyed to a hash of the credentials that produced it, so changing BACKLOGGD_SESSION or switching accounts never silently keeps you signed in as the previous one. Credentials are redacted from all log output, and no tool ever returns the session cookie.

Auth is a setup step, not something the assistant does

An MCP server receives its environment from your client's config at launch, so an assistant cannot obtain or change credentials for a running server. You configure this once; the assistant just uses it. Nothing needs to teach it how — when credentials are missing or stale, the tools return a message naming the exact variable to set.

What differs between the modes is what happens when a session eventually lapses:

Mode	On expiry
BACKLOGGD_BROWSER_IMPORT	Self-healing, as long as you are still logged in to Backloggd in that browser. The server re-imports the fresh session automatically.
BACKLOGGD_USERNAME + BACKLOGGD_PASSWORD	Self-healing. The server logs in again by itself.
BACKLOGGD_SESSION	Needs you. The assistant will report that the cookie expired and ask for a fresh one; it cannot fetch it.

For a local setup, browser import is the least-effort option: nothing to paste, and it recovers on its own.

Configuration

Variable	Default	Purpose
BACKLOGGD_READONLY	off	Do not even register the write tools.
BACKLOGGD_MIN_REQUEST_INTERVAL_MS	350	Floor on the gap between any two requests.
BACKLOGGD_MIN_WRITE_INTERVAL_MS	2500	Floor on the gap between two writes.
BACKLOGGD_MAX_WRITES_PER_MINUTE	12	Per-minute write budget.
BACKLOGGD_MAX_WRITES_PER_HOUR	200	Per-hour write budget.
BACKLOGGD_REQUEST_TIMEOUT_MS	45000	Per-request ceiling.
BACKLOGGD_MAX_RETRIES	5	Retries for stalls and transient failures.
BACKLOGGD_BATCH_BUDGET_MS	25000	Wall-clock budget for one batch call. Batch tools return partial results at this point rather than overrunning the client's tool-call timeout.
BACKLOGGD_STATE_PATH	~/.backloggd-mcp/session.json	Where the session is cached.
BACKLOGGD_DEBUG	off	Request diagnostics on stderr (never credentials).

Tools

Read (26). backloggd_whoami, search_games, get_game, get_my_game_log, check_games, get_game_lists, query_library, export_library, browse_games, browse_company, get_related_games, get_games_metadata, find_in_collection, get_play_sessions, get_journal, get_lists, get_list, get_game_reviews, get_user_reviews, get_user_profile, get_game_logs, get_activity, get_follows, get_notifications, search_users, list_filter_values.

Write (13). set_game_status, set_played_status, rate_game, set_game_like, log_game, log_play_session, add_game_to_lists, create_list, reorder_list, add_favorite_game, save_review_draft, set_follow_user, like_review.

Gated (6). remove_rating, delete_playthrough, remove_game_from_library, delete_list, delete_comment, post_comment — all behind the confirmation flow below. post_comment is gated not because it deletes anything but because it publishes publicly under your name.

The ones worth knowing about

query_library is the main one. Backloggd's library URLs are a filter grammar, and this exposes all of it: shelf, completion status, release platform, genre, year, rating and category, sorted by anything including avg-finish-time and shuffle.

query_library(shelf: "backlog", release_platform: "PS5")     → what do I own that runs on PS5?
query_library(shelf: "backlog", release_platform: "Wii U")   → what would I have to emulate?
query_library(shelf: "backlog", sort: "shuffle")             → just pick something

A caveat on avg-finish-time: it ranks longest first by default, and order: "asc" does not give you short games — it surfaces the ones with no recorded completion time at all (MMOs, live-service, obscure titles). There is no clean server-side "shortest games" query; take an ascending page and check real hours with get_games_metadata.

Platform and genre accept plain names — "PS5", "Meta Quest 3", "RPG" — and are validated against the real vocabularies before the request goes out. That matters because Backloggd answers an unrecognised slug with an HTTP 500, so a typo would otherwise surface as an opaque server error. It also means an empty result is trustworthy: nothing matched, rather than the query being malformed.

browse_company returns a developer's or publisher's whole catalogue with your shelf state attached to every game, 60 per request. Good for "which FromSoftware games haven't I played", and for franchise gap-hunting.

check_games takes a pile of titles and reports, per game, the shelf, rating and optionally which of your custom lists contain it.

Large batches are bounded rather than unbounded: the call has a wall-clock budget and returns partial results — flagging notAttempted and listsPartial — instead of blowing past the client's tool-call timeout and losing everything. Progress is cached (resolved games for a day, the list index for five minutes, resuming where a timed-out scan stopped), so simply calling again finishes the job. In practice a 40-game batch bounded at ~26s completes on the second call in ~15s, and 100 games means three calls of at most 40 each.

find_in_collection searches shelves and every custom list at once — necessary because Backloggd's list pages ignore the filter grammar entirely.

get_games_metadata costs one request per game, and says so. Prefer query_library when the set is really a library query; use this for list contents, which cannot be filtered server-side.

Ratings are always on the 0.5–5 star scale shown on the site. Backloggd stores them internally as 1–10; that conversion happens inside the server and never leaks into a tool argument.

Safety

Deleting things on Backloggd is permanent — the site offers no undo — so the destructive tools use a two-phase confirmation rather than a confirm: true flag, which a model can simply set for itself.

The first call cannot perform the action at all. It reads back exactly what would be destroyed and returns that inventory together with a server-generated token:

{
  "status": "confirmation_required",
  "summary": "Permanently delete ALL of your Backloggd data for \"Elden Ring\". This cannot be undone.",
  "willBeDeleted": {
    "shelf": "backlog",
    "rating": 4.5,
    "playthroughCount": 2,
    "playthroughs": [{ "id": 881, "hasReview": true, "reviewPreview": "One of the best…" }]
  },
  "preserved": "Nothing is preserved. The game is removed from your account entirely.",
  "confirmation_token": "confirm_96701e1ab900c8a7db6f1c2e"
}

Only a second call carrying that exact token proceeds. The token is random, single-use, short-lived, and bound to the specific action and game — one minted for deleting a rating cannot be replayed to delete a library entry, and one minted for game A cannot be used on game B. Because it cannot be guessed or constructed, the only route to a successful delete runs through that preview being surfaced in the conversation, which is the point: you get to see what is about to be destroyed before it happens.

Other protections:

• Toggle-safety. Backloggd's /log/ endpoint is a toggle, not a setter — posting backlog for a game already on the backlog silently removes it. set_game_status always reads current state first and sends only the changes that are actually needed.
• Shelf preservation. log_game carries forward shelves and flags you did not mention, so writing a review can never quietly move a game off your backlog.
• Read-only mode. BACKLOGGD_READONLY=1 means the write tools are never registered, so they cannot be called at all.
• Session preservation. log_play_session re-sends the playthrough's existing sessions alongside the new one, because the save endpoint replaces the set rather than appending to it — omitting them would silently delete your play history for that game.
• Filter validation. Platform, genre and category values are checked against the real vocabularies before any request is made, so a typo becomes a "did you mean" instead of an HTTP 500.

Automation posture

Backloggd's robots.txt targets crawlers and AI training scrapers, and disallows several of the paths this server uses. This tool is not a crawler: it acts only as the signed-in user, on that user's own data, doing things they could do by hand in their browser — the same posture as a browser extension or the community WebView mobile app. That is a considered reading, but the operator's wish to limit automated traffic is clear, so the server is built to honour the spirit of it:

• It sends an honest, identifiable User-Agent naming the tool and this repo. It does not impersonate a browser.
• Requests are serialised — never parallel — with a floor on the gap between them, and a much stricter budget on writes.
• A circuit breaker stops all traffic for 15 minutes after repeated 429s. Hammering an endpoint that is already rate-limiting you is what escalates into a restricted account.
• Responses are cached so repeat questions cost zero requests.
• It only reads your own data and pages you can already see. It does not bulk-harvest the public catalogue.
• If Backloggd ever puts up a bot challenge, the server fails with a clear message rather than trying to evade it.

Backloggd is a small, Patreon-funded site run by one person. Please do not raise the rate limits just because you can. If you are the operator and would like this to change or stop, open an issue.

Maintenance

Backloggd's markup will change eventually. When something starts returning empty results:

npx backloggd-mcp --selftest

This exercises every read path against the live site and reports which ones broke. It runs reads only and never touches a write endpoint.

To re-derive the endpoint map after a Backloggd redeploy, the front-end bundle contains every AJAX call site as a plain string literal:

curl -s https://static.backloggd.com/assets/application-<hash>.js | npx js-beautify | grep -oE 'url: *"[^"]*"' | sort -u

The <hash> changes each deploy; read the current one from the <link rel="preload"> tag on any page.

Development

npm install && npm run build && npm test

Parsers are pure (html) => T functions tested against saved HTML fixtures in test/fixtures/, so a markup change fails loudly and locally instead of silently in a chat. No test in the suite performs a network request or a write.

The fixtures are real pages captured from a signed-in session, then sanitised before being committed:

• CSRF and authenticity tokens replaced with a placeholder;
• pages carrying private account settings not kept at all;
• third parties anonymised — other users' names, numeric ids, avatar URLs and review prose are replaced with synthetic stand-ins, since those people did not agree to appear in this repository. The parsers only care about structure, so nothing is lost.

Refresh a fixture by saving the equivalent page, then run node scripts/anonymize-fixtures.mjs <your-username> before committing it.

License

MIT