TourClaim by Copernican

tourclaim

TourClaim by Copernican files trip cancellation and interruption claims against the travel insurance that comes with a traveler’s credit card. It gathers the booking, the merchant’s cancellation policy and proof of the reason (a provider’s note for an illness, a carrier’s notice for a cancelled flight, official weather records), and prepares the claim for the card’s benefit administrator, who decides coverage. Copernican charges 10% only if a claim is reimbursed.

This repository is the Python CLI, SDK and MCP server for TourClaim by Copernican, with a companion Node CLI. Give your app, assistant, or terminal a travel-claim workflow: save a traveler’s answers, collect the evidence they choose to share, hand them the authorization to sign, and follow their claim. Works with any assistant that can run shell commands or call the API; no enrolled tour operator or booking-platform integration is required.

Review mode (as of October 2026). The developer API, both CLI editions and the MCP server create synthetic claims and file nothing with an insurer. Use fictional booking and medical data only. Travelers start real claims with the online claim form. tourclaim status shows the current mode, and every intake and claim the API returns says which mode it came from.

For developers, agents, and platforms

TourClaim’s service reviews credit-card travel benefits, organizes receipts and cancellation evidence, coordinates medical-provider evaluation when needed, and handles claim preparation, filing, and follow-up. A traveler can bring a flight, hotel, or tour booking directly. Coverage, reimbursement, and clinical documentation depend on the relevant benefit administrator or provider.

The package exposes saved intake, selected email and file evidence, traveler authorization, submission to Copernican, and status. The API and both CLI editions currently use synthetic review mode: no insurer filing, payment, or clinical service is triggered. To start a real claim today, the traveler uses the online claim form, where they supply their documents and payment details securely.

• Terminal agents: use either CLI with --json; the traveler approves sign-in and signs in their own browser.
• Python applications: use tourclaim.Client from the Python edition.
• Platforms and tool-calling assistants: use the developer guide and OpenAPI schema.

Existing /muse URLs and key formats are compatibility details and continue to work. Each connection acts for one traveler, not an operator or a platform-wide account.

What it does

TourClaim files trip cancellation and interruption claims against the travel benefits of a traveler's credit card. This tool drives TourClaim's connector API on behalf of one traveler:

1. Sign in. The traveler opens the sign-in page in their own browser, types the code shown in the terminal, and approves. The tool saves a key that belongs to that traveler.
2. Start a draft with whatever the traveler has said, then answer the questions the API says are still open.
3. Add evidence the traveler chooses to share: receipts, itineraries, a doctor's note they already have, and booking or cancellation emails.
4. The traveler signs. They review the draft and sign an authorization in their own browser. This tool cannot sign for them.
5. Submit the signed draft, then check the claim's status.

Nothing in this tool or the API decides whether a loss is covered, or promises reimbursement or a medical note. Copernican charges a 10% fee only when a claim is reimbursed; no payment is taken through this tool. Only bookings charged in US dollars are supported.

For AI agents, read AGENTS.md before driving this tool.

Install

The published Python CLI and SDK require Python 3.9+. The ordinary CLI has no runtime dependencies.

pip install tourclaim

tourclaim --help

Or: uvx tourclaim --help

See python/README.md for the library and CONTRIBUTING.md for building the Node edition from source. The Node edition requires Node.js 18.3+; its package is released separately on npm by the release workflow.

Request production access

Testing is self-service. Install the CLI and run tourclaim login to create a traveler connection. No approval is needed to test with fictional data in synthetic review mode.

Live access requires Copernican’s approval. Complete the integration request form. Include your company or product, website, use case, expected volume, and intended launch date. Our team reviews requests and replies by email.

Submitting a request or creating a test key does not enable live access. Each traveler must still authorize their own connection and sign their claim.

MCP for AI assistants

TourClaim includes a local MCP server with 17 tools, browser sign-in, and the same traveler consent and signing requirements as the CLI. Install uv, then add this to a client that uses mcpServers:

{

"mcpServers": { "tourclaim": { "command": "uvx", "args": ["--python", "3.12", "--from", "tourclaim[mcp]==0.2.3", "tourclaim", "mcp"] } } }

See MCP.md for all tools, VS Code/Copilot configuration, authentication, and limitations. The official registry identity is io.github.tourclaim/tourclaim; server.json is published by the release workflow after PyPI succeeds. Like the CLI, it uses synthetic review mode (see the note at the top).

Quickstart

# 1. Connect to the traveler's account. Opens a page; the traveler enters the code shown.

tourclaim login

2. Find the card the booking was paid with (by product name, never a card number).

tourclaim cards search sapphire

3. Start a draft with what the traveler has said so far.

tourclaim intake start --set merchant_name="Example Air" --set booking_ref=EXA-482913 \ --set reason_category=airline_cancellation

4. Answer what is missing. The draft id comes from step 3.

tourclaim intake set trip_date=2026-03-04 booking_amount=250.00 refunded_amount=50.00 \ currency=USD card_product_id=412 other_insurance=no \ narrative="Example Air cancelled flight EX 204 the night before departure."

5. Add the evidence the traveler agreed to share.

tourclaim intake attach receipt.pdf --type receipt tourclaim intake add-email --eml cancellation.eml

6. The traveler reviews and signs in their browser. --wait returns once they have.

tourclaim intake sign --wait

7. Submit, then follow the claim.

tourclaim intake submit tourclaim claims list

Commands

Every command accepts these global options:

Commands never prompt when stdin is not a terminal; they fail with a message saying which flag to pass instead.

tourclaim login

tourclaim login [--no-browser] [--scope <scope>]... [--force]

tourclaim login --with-token [--force] < key.txt

Signs in with a device code. The tool prints the sign-in page (https://app.getcopernican.com/connect/cli) and, on a line of its own, Enter this code on that page: WDJB-MJHT. It opens the page in the browser when run in a terminal (not with --no-browser). The traveler types the code shown in the terminal and approves; the code is never put in a link, so a link someone else sends cannot sign anyone in. The tool polls at the interval the API asks for, slows down when told to, and gives up when the code expires. It then saves the key and prints the account and expiry: Signed in as pat@example.com (key expires 2026-11-03 18:00 UTC, in 30 days).

• --scope asks for fewer permissions: any of intakes:write, evidence:write, claims:submit, claims:read (repeat the flag or separate with commas). The default is all four.
• If a valid key is already stored for the API URL, login reports it and exits 0 without starting a new sign-in. --force gets a new key. Whenever a sign-in replaces a stored key, the tool sends that key along with the sign-in, and the server retires it as it issues the new one (if it is a tourclaim login key for the same account; otherwise the tool warns that the old key still works). Drafts are not lost: see Which drafts a key can reach.
• The tool waits until the code expires and then checks once more, so an approval made in the last seconds still signs in. While it waits, a brief server error (HTTP 502, 503 or 504) or a dropped connection does not end the sign-in: it tries again, honoring Retry-After, and gives up only after 3 failures in a row.
• A traveler can hold at most 5 connections. When a new tourclaim login would go over, the server retires the account's oldest tourclaim login key; it never touches keys made for other apps. If all 5 belong to other apps, the sign-in fails (exit 3) with the server's reason: disconnect one at https://app.getcopernican.com/connect/muse first.
• --with-token saves a key the traveler already created at https://app.getcopernican.com/connect/muse. It reads the key from stdin when piped, or from a hidden prompt on a terminal, and checks it with the API before saving. Such a key does not say whose account it is, so the tool prints Signed in (key expires ...) without an email. A key is never accepted as a command-line argument.
• With --json, the first line is {"event":"device_code","user_code":...,"verification_uri":...,"expires_in":...,"interval":...} so an agent can show the page and the code to its human; the last line is {"event":"signed_in",...}, with account_email when the key says whose account it is.

tourclaim logout

Revokes the key in use on the server, then deletes the stored copy. The stored copy is deleted even when the server says the key was already invalid. If the server cannot be reached, nothing is deleted, so you can try again.

tourclaim status (alias whoami)

Shows the API URL, whether the connector is enabled, the mode, the signed-in account, key expiry and permissions. The first line in review mode is REVIEW MODE: CLAIMS ARE SYNTHETIC AND NOTHING IS FILED. Exits 0 when signed in, 3 when not signed in or the key is rejected, 7 when the connector is disabled.

tourclaim cards search

Searches the card catalog by product name (at most 100 characters, at most 30 matches). Use a result's id as card_product_id. Finding a card does not mean it covers the loss. The command refuses input that looks like a card number.

tourclaim intake start

tourclaim intake start [--set <field>=<value>]... [--fields-file <file>] [--idempotency-key <key>]

Starts a draft. Every field is optional at this point; the output lists what is missing and up to three questions to ask next. Run tourclaim intake list first: the traveler may already have a draft for the same trip. The command sends a random Idempotency-Key unless you give one. If it fails or times out, run it again with the same --idempotency-key and the same fields to get the same draft rather than a second one; the error message includes the key it used.

tourclaim intake list [--offset ]

Lists the traveler's drafts that were never subm