@tempoxyz/mercator

@tempoxyz/mercator

Connect supported agent clients to the Mercator remote MCP server.

Install

curl -fsSL https://mercator.sh/install.sh | sh

This downloads a checksum-verified standalone executable for macOS or Linux; Node.js and Bun are not required. Windows users can install the standalone executable with PowerShell:

irm https://mercator.sh/downloads/latest/install.ps1 | iex

Or install the npm package with Node.js 22 or later:

npm install --global @tempoxyz/mercator
mercator setup

Or run Mercator with Nix, which supplies its required Node.js runtime:

nix run github:tempoxyz/mercator -- setup

Install it into your Nix profile with nix profile install github:tempoxyz/mercator.

Setup:

• Detects supported client CLIs and desktop configuration.
• Lets interactive users select from every detected client.
• Installs the Mercator MCP integration and one local Codex/ChatGPT plugin.
• Uses the public tempoxyz/plugins plugin marketplace for Claude Code and Grok CLI.
• Connects native OAuth clients to /mcp/auth; Grok setup completes browser authorization immediately and stores its bounded bearer in Grok's user configuration.
• Upgrades existing Mercator /mcp registrations while preserving unrelated custom endpoints.
• Never prints or copies wallet keys or API keys.
• Preserves successful integrations when another target fails.
• Reports installed, current, skipped, and failed work.
• Ends with three copyable prompts from the public suggestion catalog or bundled fallback prompts.

The desktop plugin includes the Mercator skill by default. Pass setup options through the bootstrap command after sh -s --:

curl -fsSL https://mercator.sh/install.sh | sh -s -- --client codex --no-skill
mercator doctor

The same controls work when setup is rerun directly: mercator setup --client codex --no-skill.

The installer verifies the release checksum and atomically installs mercator into ~/.local/bin. Release artifacts are served anonymously through the Mercator Worker while the source repository remains private. It adds that directory to the active shell's profile when needed. Download or validation failures during a reinstall preserve and use the existing executable. Run mercator --update to install a newer standalone release.

Setup is best-effort: failures in one client or optional plugin, guidance, client-managed payment, or readiness phase are reported without undoing successful work. Run mercator doctor for a strict readiness check.

Setup sends anonymous, finite funnel events through Mercator to PostHog: CLI version, platform, architecture, installation channel, interaction mode, selected client IDs, bounded outcomes, and elapsed time. It never sends account identity, hostname, paths, configuration content, wallet data, or raw errors. Disable it with MERCATOR_TELEMETRY=off or DO_NOT_TRACK=1; it is also disabled in CI and for custom MCP endpoints.

Setup controls

Option	Behavior
No option	Install the desktop plugin. Interactive setup shows every detected client checked by default; non-interactive setup configures all detected clients.
--client <name>	Configure one client; repeat for several. Supported IDs: claude, cline, codex, continue, cursor, gemini, grok, hermes, kiro, lmstudio, openclaw, vscode, windsurf, and zed.
--url <url>	Use another Mercator MCP endpoint, including a local development endpoint.
--dry-run	Preview all setup work without writing changes.
--yes	Configure every detected client and apply without interactive prompts.
--manual	Print generic MCP/OAuth connection instructions without configuring integrations. Incompatible with --client, --force, and --remove-agents; supports --url and --verbose.
--force	Recreate MCP registrations; Grok repeats Account authorization.
--color / --no-color	Enable or disable color in interactive output. NO_COLOR is also supported.
--plugin / --no-plugin	Enable or disable the local Codex/ChatGPT desktop plugin. Enabled by default.
--skill / --no-skill	Include or omit the Mercator skill inside the desktop plugin. Included by default.
--agents / --no-agents	Enable or disable managed Codex AGENTS.md guidance. Enabled by default.
--remove-agents	Remove only managed Codex guidance and stop; incompatible with --force and --no-agents.
--verbose	Retain setup progress and print bounded runtime, integration, readiness, and error context.

Run mercator setup --help for generated setup options or mercator status for detected client connection state. Run mercator account to manage the hosted wallet grant, limits, funding, and revocation. See the client support checklist for client coverage.

Bootstrap installer controls

Variable	Behavior
MERCATOR_BIN_DIR	Set the executable directory; highest precedence. Relative paths are resolved before installation.
MERCATOR_INSTALL_DIR	Set the executable directory when MERCATOR_BIN_DIR is unset.
INSTALL_DIR	Generic fallback when neither Mercator-specific directory is set.
MERCATOR_INSTALLER_URL	Download a specific trusted HTTPS release installer.
MERCATOR_NO_MODIFY_PATH=true	Leave shell profiles unchanged and print the PATH command instead.
MERCATOR_SKIP_SETUP=true	Install the CLI without running setup. Run mercator setup later.

Boolean controls accept 1/0, true/false, yes/no, or on/off, including common uppercase and title-case forms. An unrecognized value warns and uses true, avoiding optional setup and profile changes. Put installer variables on the sh side of the pipe so they reach the installer:

curl -fsSL https://mercator.sh/install.sh | \
  MERCATOR_NO_MODIFY_PATH=true MERCATOR_SKIP_SETUP=true sh

HOME is needed only when no install directory is provided. The installer refuses /, parent traversal, and destinations resolving to /.

Claim MACH

Paid MCP jobs use the hosted wallet authorized by the agent client. The CLI does not create or inspect that wallet.

Local REST feedback handoffs cost nothing but require an existing local wallet to prove it is the original job payer.

mercator account claim github
mercator account claim x

The claim commands open Account with the claim controls visible. Confirm GitHub or X there; the one-time MACH grant goes to the Tempo wallet authenticated in Account, which is also the wallet used for hosted MCP payments. If needed, Account asks you to sign in before continuing.

Local REST recovery

Use this only when MCP submission and one identical retry fail and an existing, externally funded local wallet is available. Do not create a wallet in response to a failed submission. The approved plan, total, and idempotency key must remain unchanged.

mercator local wallet status
mercator local wallet balance
mercator local submit --url <jobs-url> --body <json> --max-spend <amount>
mercator local job get <job-id> --wait

Waiting polls the same durable job with bounded backoff for up to 15 minutes. If it remains pending, run the same command to resume waiting; do not resubmit the job.

Uninstall

mercator uninstall

Wallets, keys, balances, and sessions are preserved.

Documentation

See the Mercator documentation or run mercator --help.