Tomebound

Automation and integrations

Work with your collection outside the app: a command-line tool, agent access over MCP, and personal access tokens.

Command line (CLI)

  • Tomebound has a command-line tool, tomebound (short alias bp), for managing your collection from a terminal.
  • Install or upgrade with npm install -g tomebound (Node.js 22 or newer), then run bp login to sign in with read access. Run bp login --write when you need to edit.
  • The CLI uses dynamic registration: each new login asks you to approve its loopback connection on the Tomebound consent page. bp logout clears local credentials; revoke the connection in Settings → Connected apps to stop server access immediately.
  • It can search, add, edit, move, import, export, undo, and recover, and prints machine-readable output with --json plus meaningful exit codes for scripts and agents. Every edit shows a preview and asks for confirmation (--yes skips the prompt). A result other than applied, such as not found or ambiguous, exits with an error code. Use bp export --all to retrieve every inventory page, or add --deck NAME for every page of a deck list. Without --all, export returns one page. Failed requests return a nonzero exit code and leave an existing export file unchanged. Run bp help or bp <command> --help for options.
  • For a confirmed bulk job, the CLI saves a local continuation journal so restarting the same command can resume the original operations without repeating the saved portion. Ordinary edits do not create this journal. Expired unconfirmed previews, rejected zero-write jobs, and other proven terminal results clear it; running the command again requires a fresh preview and confirmation. Transport interruptions keep the journal for receipt reconciliation. Expired jobs with an unknown saved portion keep the journal until you explicitly discard it; the CLI reports the confirmed saved count when available. Check collection history before re-previewing only the remaining changes. Repeat a mutation command with --discard-pending to forget its local journal without changing saved cards. Bulk undo follows the original confirmed job until complete; a running undo must be continued before starting a fresh undo. A terminal conflict ends that undo and does not block later unrelated undos.
  • Use bp validate-deck "deck name" to check a recipe against its saved format. Validation reports violations and warnings without changing the deck. Validation fetches Oracle text for command-zone cards from Scryfall, without changing the deck. The lookup waits up to eight seconds; if it fails, rules that need missing Oracle text remain pending lookup. Type-based commander violations still appear. Unknown formats are reported as unvalidated.
  • Use bp card-allocation <scryfallId> to compare owned copies with deck claims. Allocation also accepts --item-key, --finish, --language, and --include-maybe; its deck list is limited to ten rows with complete totals. Find ids with bp search "..." --json. These commands need only read access.
  • The CLI connects to https://api.tomebound.app. Saved connections to the retired production hostname migrate silently and keep their credentials; custom API origins remain unchanged. Saved OAuth credentials are used only at their API origin; another origin requires a separate login.

Agents and MCP

  • Connect external AI assistants to https://api.tomebound.app/mcp and name the server tomebound. OAuth defaults to collection.read. Write access requires the client to request collection.write and your approval on the Tomebound consent page.
  • New to Tomebound? Sign up during the connection flow; you do not need to visit the web app or save a collection first. An empty collection gives your agent next steps: preview an import from a pasted list, CSV, or deck link, add a few exact printings, or open https://tomebound.app/?scan to use the web scanner. Imports and additions need approved write access. Agents can present previews and printing choices directly in conversation without an embedded app UI.
  • After signing in, check the client name (self-reported), redirect host and requested access, then choose Approve or Deny. Tomebound can remember approval for a dynamically registered client when the authenticated account, client, redirect and scopes match and the browser flow is verified. Clients using a shared HTTPS metadata identity or partner client ID always ask for consent when connecting or reconnecting. Requesting different access needs another approval. Complete the connection in the same browser where you started it.
  • Redirects are limited to loopback for desktop clients and the documented Claude, ChatGPT, Meta Muse, Cursor and VS Code callback hosts and paths. Clients can connect through dynamic registration, supported HTTPS client metadata documents or a pre-registered partner client; all require the same sign-in, consent and PKCE protections. Connections created before Tomebound consent was introduced need to reconnect, including existing Claude connectors.
  • Claude Code can use the runtime port chosen by its local callback listener when its loopback URI is listed in a supported client metadata document. Only the port can vary; scheme, host, path and query still match. Dynamically registered callbacks remain exact, and code exchange always uses the exact URI from authorization.
  • Claude Code: run claude mcp add --transport http tomebound https://api.tomebound.app/mcp, then open /mcp to sign in.
  • Codex CLI: run codex mcp add tomebound --url https://api.tomebound.app/mcp, then codex mcp login tomebound --scopes collection.read.
  • Claude Desktop: add a custom connector in customize → connectors with https://api.tomebound.app/mcp, then connect and enable it for the conversation. Workspace owners may need to add it first.
  • ChatGPT / OpenAI dots: open Plugins on the web, select the plus button, and choose Add custom MCP server. Enter the MCP URL, choose OAuth with dynamic client registration, leave static credentials empty, and create the plugin. Install Tomebound from your personal plugins, complete sign-in and consent when prompted, then type @ in a Work chat and select Tomebound. Once a directory listing is available, connect it there instead. Claude also supports a custom connector before a directory listing is available.
  • OpenClaw: add the remote URL under mcp.servers.tomebound in ~/.openclaw/openclaw.json with transport streamable-http and auth oauth, then run openclaw mcp login tomebound. The setup guide includes a read-only scope and a personal access token alternative. Use a private instance for a personal collection.
  • Meta Muse: ask it to add a custom connector for https://api.tomebound.app/mcp. This setup is not yet verified end to end with Tomebound. Use OAuth only if supported, or the connector’s secure Bearer credential control with a read-only personal access token; never paste tokens into conversation text.
  • See https://tomebound.app/integrations.html for complete ChatGPT, Claude, Meta Muse, OpenClaw, Codex, Claude Code, Cursor, VS Code, and CLI setup instructions. Directory availability and client menus can vary.
  • Ask your connected agent to import an attached Moxfield export, estimate your collection’s value, compare a deck list with your owned cards and the cost of missing copies, build a deck recipe from a list, or export to ManaBox. Available requests depend on the tools enabled in your client. Review imports and deck creation before saving; a deck recipe does not add cards to owned inventory. Missing prices are unknown, not zero. Agent collection values, owned-card prices, price filters and exports use the daily price snapshot without adding prices to your saved collection. Results include the snapshot date, unpriced counts and whether prices are available, partial or unavailable. Partial totals are marked, and entries whose quotes could not be loaded are counted separately. Collection value supports USD, EUR and tix when the snapshot has those quotes; general inventory filters, exports and deck owned values use USD. Finish-specific prices follow the app’s fallback rules, and localized cards use the matching English printing when that mapping is available. Deck owned value matches the deck page: its displayed printing price times the exact copies owned, capped at the decklist quantity and excluding the maybeboard. A separate allocated-copies value uses the actual finishes of allocated exact and alternate copies. Zero-dollar quotes count as unpriced. If a price load fails or times out, estimates include only successfully loaded or cached quotes, including any USD fallback loaded from the daily web snapshot. Prices stored on collection rows are not used as a fallback. A failed refresh keeps previously loaded prices until a retry succeeds; one request timing out does not stop other requests from loading prices. Daily worker prices switch only after the complete new snapshot has uploaded.
  • Agent card-detail reads use daily metadata snapshots. Missing details are reported as unavailable rather than a complete zero-match answer. Set-name filters use the hydrated names shown in results. Unknown legality formats are rejected with valid choices; edh means commander, while cEDH is not a separate format. Unknown legality values and release dates are excluded from both positive and negated matches. A card with loaded details but genuinely no power can match a power-not-equal condition.
  • Connected agents and Tomebound chat can send feedback or bug reports to the developer after you confirm the wording, up to 10 submissions per UTC day.
  • Tool results are shared with the agent platform you connect under your direction. Its privacy policy and settings govern its copies of that data. Tomebound does not sell your data or use it to train AI models. See https://tomebound.app/legal.html#connected-apps for access, providers, retention, and revocation. If you send feedback or a bug report through a connected app, Tomebound stores your message, the app's name and the time, and emails them to the developer. Tomebound also records how the service is used and how well it works, such as which parts of the app and which connected apps and tools are used, how imports and other actions turn out, and errors. This is linked to your account so problems can be found and fixed, and it's used only to run and improve Tomebound. It doesn't include the contents of your files, card lists or messages.
  • Tomebound requires a preview for agent changes that remove cards, decks or containers, or touch more than 25 rows: the agent must first run the change as a preview, then repeat the same request with that preview's token. Showing you the preview before it applies is up to the agent, so prefer clients that ask first. Smaller adds and edits can apply in one step. Agent writes match card, set, deck, and container names literally, ignoring case, accents, and normalized whitespace; a card name also ignores punctuation when no card has that exact name. Split-card face names and exact set-code aliases are accepted. Near matches are suggestions that require a choice before writing, including additions to deck recipes. Ambiguous destinations and explicitly requested printings require a choice too. Exact name-only additions to a deck recipe use Scryfall’s default printing and report its set and collector number so you can ask to change it. Physical collection adds still require a printing choice when several match. Requested finishes and languages must exist for the selected printing. If a saved card lacks finish metadata, a finish edit looks up its printing; an unknown printing requires clarification without changing the finish. Other edits still work. Finish or condition annotations in parentheses or brackets are removed from saved names only after the remaining name matches exactly; conflicting explicit finishes are rejected. Unknown boards or location types are rejected; legacy binder and box types mean container. Large inventory requests prepare a whole-job preview in working groups of 200 items, or 75 when adds require name-only lookups, explicitly request a non-English language, or need a different-language printing. These group sizes are not a total request limit; request and storage size limits still apply. The agent follows the supplied continuation until the entire preview is ready, then confirms the whole job once. An exact Scryfall ID keeps its printing language when no language is requested. Deleting more than one row needs an explicit all-matches flag and a filter, and unknown fields are rejected. Unconfirmed bulk previews expire after ten minutes. Confirmed bulk jobs retain their original operations and saved progress for up to 30 days. A retry after a transport interruption continues the same confirmed job. Unrelated edits can be preserved by rebasing the remaining changes onto the current collection, even after part of the job was saved. A conflict with edits to the same cards is terminal: the result reports saved and unsaved card totals, with up to 25 item keys for each portion, and lists up to 25 conflicting card keys or names. Make a fresh request only for the unsaved cards; its preview reads the current collection and requires confirmation. When more than 25 cards remain unsaved, compare the original request against the collection before requesting the unsaved portion. No remainder continuation is issued. Invalid or exhausted rebase records report confirmed saved counts while keeping the overall outcome unknown. Do not include the saved portion in that new preview. Ordinary mutation retry keys last ten minutes. A committed change whose verification fails returns a warning rather than inviting another write. Temporary printing lookup failures are reported as retryable errors.
  • In the native iOS app, a large selection first prepares a preview. Save confirms that entire preview; the general sync retry control cannot confirm an unreviewed preview. Confirmed jobs resume their original operations after interruptions. If the server proves nothing was saved, reports a revision conflict or inconsistent saved receipts, or the saved job is unavailable or past retention, the app clears the pending job and refreshes the collection so editing can continue. Check the refreshed collection and history before preparing a replacement change, because an unavailable or expired job can have a saved portion.
  • A recovery point is created before every applied agent change; the one before a change of more than 25 rows is kept for up to 30 days even when many changes follow. Undo reverts an agent's last change only while its affected cards are unchanged; otherwise restore its recovery point. An interrupted bulk job retains history and undo for the saved portion. Bulk undo may continue across several requests; a fresh undo is refused while that undo is still running. A terminal undo conflict ends that job and reports its saved portion; it does not block undo of later unrelated changes. Undo is not itself undoable through undo_last_mcp_change: a second undo finds the next older eligible change or reports that none exists. A chat confirmation that was already applied and undone requires a fresh preview. Previews that are never confirmed do not create recovery points or undo records.
  • Agents can import pasted card lists or CSV from Tomebound, Moxfield, ManaBox, Archidekt, Deckbox, or TCGplayer, and public deck links from Moxfield, Archidekt, MTGGoldfish, MTGTop8, EDHREC, Scryfall, raw GitHub or Gist files, or Pastebin. TappedOut, Deckstats and AetherHub links can't be fetched; paste their decklists instead. Import accepts up to 5,000 rows and 4 MiB of text per job, with 1–1,000 copies per source row. Missing finish, condition, and language default to normal, near mint, and English, or your supplied defaults; values parsed from the source always win, including a blank Moxfield or Deckbox Foil field meaning non-foil. Sideboard and maybeboard cards are excluded from collection imports unless you explicitly include each board. Without a destination, or with a blank one, rows keep the file's own locations: ManaBox binders become containers and ManaBox decks become decks, matching existing ones of the same type by name; a name matching more than one asks first, and ManaBox list rows such as wishlists are excluded as not owned. A deck the import creates gets the rows in its decklist; an existing deck named by the file receives the copies and keeps its decklist. Import destinations use deck:<name>, container:<name>, or a type/name object for an explicit type. Bare names match existing decks and containers by the whole name, ignoring case and accents and normalizing Unicode whitespace. If both a deck and container match, the agent asks which one without writing; unmatched bare names create a container shown in the preview. Imports never match part of a name or a similar name. Importing into a deck adds physical copies and merges recipe rows with their original boards; the preview shows both. Review board counts, each row's location, containers that will be created, selected printings, skipped rows, merged duplicates, total quantity, and estimated USD value before applying. Unavailable or mismatched printings are excluded; unknown prices are listed separately. Name-only rows show the selected printing marked as defaulted. The preview and cached apply result list every excluded or unresolved row and its quantity. If the result cache is unavailable, replay returns a compact history receipt with counts and up to 50 omitted rows, without printing suggestions, and reports how many additional rows are not listed; partial imports state how many copies were imported out of the source total and how many rows and copies were not imported. Applying a partial import requires a preview that disclosed those omissions. Imports too large to save safely with their history must be split.
  • Imports and new decks always require a preview before applying, including small ones. The preview lasts ten minutes and is tied to your current collection. Applying uses the stored printings and records one undoable change and a recovery point. The agent can continue a large lookup across calls without changing your collection, including batched lookups for non-English printings. After a lost response, retry the same preview token, with or without the original arguments. If it has expired, check recent changes for the preview's apply ID before starting again; when history is inconclusive, verify the collection first to avoid duplicate imports.
  • Agents can create a deck recipe from Arena, MTGO, Moxfield, or plain decklist text, supported collection CSV, or a supported deck link, without adding any owned cards. CSV preserves supplied printing, finish, condition, and language fields. MTGTop8 .dec, Forge .dck, and Cockatrice .cod XML files are rejected with a format-level explanation; export plain-text lists or CSV instead. Commander, companion, and board sections are preserved. Every row must resolve; an owned-only request also stops when copies are missing. Existing decks are never overwritten. Agents can validate an unsaved list, check available exact and alternate copies, see owned copies reserved by other decks, and build a buy list for copies not owned in any printing with Scryfall price estimates and purchase links. Copies reserved by other decks still count as owned and are not on the buy list. Copies filed in the target deck give it priority for loose copies needed by its recipe; copies physically filed in other decks stay reserved. Available counts include copies already filed in the target. Prices are estimates, not live seller offers; unavailable prices remain unknown.
  • Agents can export all owned cards or the physical cards in a named container or deck as Tomebound, Moxfield, or ManaBox CSV, or JSON. Deck export scope means cards physically stored there, not the planned recipe. JSON contains the selected collection rows, not a full backup. Files below 200 KiB are returned directly; larger files up to 20 MiB use a private download link that expires after 15 minutes. Anyone with that link can download that export until it expires.

Connector tool reference

  • These are the tools available to external connectors for a normal account with approved read and write access. Read means readOnlyHint is true; Write means it is not. Read-only connections can use tools requiring collection.read. Each tool’s required scope is listed below. Queries support up to 100 same-field equality alternatives with OR or IN (...); simple mixed OR expressions allow up to 16 combinations. Inventory SQL also supports NOT, NOT IN, BETWEEN, IS NULL, ILIKE, LIKE wildcards (% and _), DISTINCT, COUNT/SUM/AVG/MIN/MAX, GROUP BY, HAVING, AS aliases, multiple ORDER BY fields, numeric arithmetic, LIMIT and OFFSET. Text comparisons are case-insensitive. Rules text uses oracle (also oracleText, oracle_text, text or rulesText). In SQL expressions, free text such as artist, container or deck names, and tags accepts wildcard matching; structured LIKE supports end % wildcards on location, artist and tags, but not _; rarity, finish, condition, language and set codes require = or IN (...) instead of wildcards. Split lists longer than 100 values into multiple queries. Outside inventory, LIKE supports % at the ends of a value, not _. Joins, subqueries and other functions are not supported. Aggregates report unknown input counts; numeric aggregates with unknown inputs return null. Unavailable price data prevents price-dependent queries, and missing card metadata is reported.
  • No tool makes purchases or payments. Removals and changes affecting more than 25 rows return a preview that must be confirmed before applying. Imports and new decks also require a preview. Changes can be undone; recovery points can restore earlier collection snapshots.
Tool Description Read or write Required scope
send_feedback Send feedback or a bug report to the developer. Write collection.read
get_collection_overview Summarize your collection, containers and recent changes. Read collection.read
query_collection Filter and browse your cards, decks, containers or history. Read collection.read
resolve_printing Find a card printing and choose among matches. Read collection.read
collection_value Estimate your collection’s value and report missing prices. Read collection.read
get_value_history Read your collection’s, a container’s or a deck’s daily value history and biggest price movers. Read collection.read
card_prices Look up prices for owned or unowned card printings. Read collection.read
validate_deck Check a saved or proposed deck’s legality. Read collection.read
card_allocation Compare owned copies with the copies claimed by decks. Read collection.read
deck_ownership Compare a deck list with owned cards and estimate missing-card costs. Read collection.read
export_collection Create a CSV or JSON export of your collection. Read collection.read
import_cards Preview and add cards from a list, CSV or supported deck URL. Write collection.write
create_deck Preview and create a deck recipe without adding owned cards. Write collection.write
add_cards Add owned cards. Write collection.write
duplicate_cards Add another copy of an owned card. Write collection.write
edit_cards Edit owned card details. Write collection.write
replace_printing Replace an owned card’s printing. Write collection.write
move_cards Move owned cards between locations. Write collection.write
delete_cards Remove owned cards. Write collection.write
add_to_deck Add cards to a deck recipe. Write collection.write
remove_from_deck Remove cards from a deck recipe. Write collection.write
move_deck_board Move cards between deck boards. Write collection.write
delete_deck Delete a deck recipe and clear its physical cards’ deck location, or delete those cards with cascade. Write collection.write
list_mcp_recovery_points List saved snapshots from before collection changes. Read collection.read
restore_mcp_recovery_point Preview and restore a saved collection snapshot. Write collection.write
undo_last_mcp_change Undo the last agent change when its affected cards are unchanged. Write collection.write
search Search your collection for results an agent can reference. Read collection.read
fetch Read one of your collection search results by its ID. Read collection.read

Connected apps

  • While signed in, open Settings → Connected apps to see apps connected through OAuth, including their self-reported names, redirect hosts, access, creation dates, last use and tool calls in the last 30 days. App call counts are labeled combined because they cover all your connections for the same app registration. Counts cover today and the previous 29 UTC days, and include executed calls that fail or are retried. Usage records are kept for about 45 days. Counts start when usage recording is enabled; older calls are not reconstructed. Recording is best effort; unavailable counts are shown as unavailable, never zero. Last use also includes authenticated MCP discovery requests and may lag by up to a minute.
  • Choose Revoke and confirm to immediately stop that connection’s access and refresh tokens. Reconnecting requires your approval again. Personal access tokens are managed separately under Settings → Access tokens.
  • OAuth access tokens last one hour. Refresh tokens expire after 30 days without rotation. Active connections renew their approval window, up to one year after approval; 90 days without use also ends an approval. Dynamic client registrations renew during successful use and expire after 90 unused days. If refreshing stops working, reconnect in the client; an expired registration needs a new registration, and an expired or revoked approval needs consent again. Tomebound’s own app and hosted chat use first-party sessions rather than appearing in this list.

Personal access tokens

  • For headless or automated use without a browser sign-in, create a personal access token from the account section in settings while signed in.
  • Use it with the CLI or an agent by setting the TOMEBOUND_TOKEN environment variable.
  • Tokens carry read-only or read-and-write access and can be revoked at any time.
  • New tokens expire after 30 days by default; choose between 1 and 90 days. You can keep up to 20 active tokens. Last use updates at most once per hour. Older tokens keep their original expiry until you revoke them.

Collection chat

Ask natural-language questions and stage edits through the chat surface.

Ask questions

  • Use collection chat to ask about cards, prices, containers, tags, deck contents, and collection summaries. The three starter questions read your collection directly without waiting for AI or using your daily AI allowance. Creatures and multiple copies open matching collection filters; multiple copies means two or more copies of the same printing, finish, condition, and language in one location. The value starter shows up to ten cards ranked by price per copy. Questions about the most recently added or acquired card use its latest acquisition timestamp, while recently changed or moved questions use edit history instead.
  • Consult the Tome answers questions using the current collection and may return cards you can open in the app. While a response is being prepared, Consulting the collection appears with three stars; the stars stay still when reduced motion is enabled. For supported collection filtering requests, the reply includes view in collection instead of a results table. The link opens all matching cards with normal, editable collection filters, can be bookmarked, and works with browser Back. Queries that cannot be represented faithfully by collection filters keep their card results in chat.
  • Chat opens in a compact panel. On desktop, drag the Consult the Tome heading to move it and drag an edge or bottom corner to resize it. The panel stays inside the screen and remembers its position and size; temporarily shrinking the browser does not replace your saved dimensions. Closing chat preserves your unfinished message. The conversation and unfinished message survive reloads in the same tab while you stay signed in; pending previews are restored for up to ten minutes. Signing out or changing accounts clears that tab’s previous conversation. Reset chat appears after a conversation starts and asks before discarding pending proposals. Failed replies restore your draft unless you have already typed a new one.
  • Choose a suggested question to send it, or write your own message and choose Ask. Enter sends; Shift+Enter adds a new line. While a reply is on its way, Stop stops waiting without clearing the conversation or its previews. A reply that takes longer than two minutes, or a preview or apply that takes longer than 30 seconds, stops with a message so you can try again. If an apply's answer is lost, the change may still be applying: Tomebound refreshes your collection right away and again about 10 seconds later, and asks you to check it before applying again.
  • Collection chat requires signing in — opening it while signed out disables the message box and starter questions and offers Sign in to chat. On phones, opening chat leaves the keyboard closed until you tap the message box.
  • Plum identifies the Archivist's replies and chat button icon, sharing the curated-intent hue of decks.

Preview edits

  • Chat never edits your collection directly: every change arrives as a preview that you apply yourself. Oversized multi-item proposals must be split into smaller complete previews; chat never offers only a sample of a larger job for application.
  • Previews appear as proposed amendments. Review each entry, then choose apply changes or Discard. A preview that removes cards asks you to confirm its summary first. With multiple entries, apply all changes applies the group after confirmation; discard all clears the pending previews. Large confirmed changes continue automatically across bounded requests, showing how many cards have been saved until the job finishes or stops. Continuation refreshes authentication each round and pauses after 100 rounds; apply again to continue the same confirmed job. Jobs accepted by the server keep their confirmation cards across reloads while unfinished, even after the original preview expires. Cards return to normal expiry after a final result. Applying one preview leaves the others usable, including other copies from the same stack or other rows of the same deck. If apply all finds previews that conflict, such as two that move more copies than a stack holds, it applies them one at a time and re-previews the ones an earlier change affected so you can review them again.
  • Chat only offers a removal when your message asks to remove, delete or sell something.
  • Exact card additions may ask for a printing when the request is ambiguous.

Before changes happen

  • Chat can suggest changes, but every edit waits for your approval.
  • Tomebound checks that you are still signed in and allowed to make the change before applying it.
  • Tomebound creates a recovery point before applying a chat change, and applied chat changes appear in History, where you can undo them.
  • Each question can use up to eight collection lookups, and replies are kept short, so very broad requests may be answered in part. Questions count toward a personal daily allowance and a shared daily limit; a question your personal allowance refuses does not count toward the shared limit.