Cuebook MCP Server

Overview

Every trade starts with a cue. cuebook (alias: cbk) makes Cuebook available wherever you already work: a terminal, a script, or an AI coding agent.

Use focused commands for everyday tasks, or discover and call the full Tool surface at runtime:

• resolve assets and inspect market state;

• read sourced Cues, themes, events, filings, and disclosures;

• explore reasoning graphs, positioning, calendars, and prediction markets;

• inspect a virtual portfolio and preview paper orders;

• return deterministic JSON for agents and automation.

No exchange API keys. No wallet credentials. No real-money execution.

Related MCP server: Yahoo Finance MCP Server

Quick Start

Requirements

• Node.js 20 or newer

• A Cuebook account

Install

git clone https://github.com/cuebook-public/cuebook-cli.git
cd cuebook-cli
npm ci
npm run build
npm link

This installs both cuebook and the shorter cbk alias.

Connect your account

cuebook auth login

Your browser opens Cuebook. Review the request and approve it to connect the CLI.

Make your first calls

cuebook tools list
cuebook assets search bitcoin
cuebook market state btc
cuebook cues latest --asset btc

Why Cuebook CLI

The result is a small, self-describing command surface that works equally well for a person at the keyboard and an agent operating through a shell.

Commands

Command reference

Everyday examples

# Resolve an asset, then inspect its market state
cuebook assets search bitcoin
cuebook market state btc

# Read current market narratives
cuebook cues latest
cuebook cues latest --asset nvda --limit 5

# Preview a simulated order — nothing is placed
cuebook paper preview btc --side buy --notional-usd 100

# Read historical candles
cuebook call get_candles \
  --input '{"ticker":"btc","interval":"1d"}'

# Read arguments from a JSON file
cuebook call get_reasoning_graph --file request.json

What you can explore

The available surface can evolve. cuebook tools list always shows the current Tool names, descriptions, inputs, and safety classification.

Agent Workflows

Use the global --json flag whenever another program will consume the result:

cuebook --json assets search NVDA
cuebook --json cues latest --asset nvda
cuebook --json market state btc | jq -r '.data.quotes[0].price'

Output contract

JSON errors use a stable envelope:

{
  "error": {
    "message": "Cuebook authorization is required.",
    "hint": "Run: cuebook auth login"
  }
}

Generic Tool calls

cuebook call is the escape hatch for capabilities that do not yet have a focused command:

cuebook call <tool> --input '{"key":"value"}'
cuebook call <tool> --file request.json

An agent can start with cuebook tools list, select a Tool, assemble its arguments, and call it without relying on a hard-coded catalog.

Write Safety

Cuebook CLI fails closed around writes:

1. Known read operations run normally.

2. A write-capable or newly introduced Tool requires --confirm.

3. Confirmed writes are sent once and never retried automatically.

4. Paper-trading actions use virtual funds only.

# Blocked: explicit confirmation is missing
cuebook call place_paper_order --file order.json

# Sends one simulated paper order after review
cuebook call place_paper_order --file order.json --confirm

Confirmation is an additional client-side guard. Cuebook still applies the permissions, limits, idempotency rules, and validation required for each Tool.

Cuebook CLI cannot place real trades, transfer money, access an exchange account, or request exchange and wallet secrets.

Authentication

cuebook auth login uses OAuth 2.1 with PKCE and opens Cuebook in your browser. Access is granted only after you approve the connection.

• Credentials are stored in an owner-only local file (0600 on Unix-like systems).

• Set CUEBOOK_CONFIG_DIR to choose a different credential directory.

• Set CUEBOOK_ACCESS_TOKEN for externally managed automation; the CLI never writes that value to disk.

• Each authorized CLI uses one Agent connection.

• A Cuebook account can keep up to three active Agent connections.

Disconnect and release a slot

cuebook connections

Choose Disconnect next to the connection you no longer use. Local logout removes credentials from the current machine; disconnecting in Cuebook also releases the Agent slot.

Configuration

The default endpoint is https://cuebook.xyz/mcp.

Troubleshooting

Start with:

cuebook doctor

cuebook doctor never prints OAuth tokens.

Development

npm ci
npm run check

The quality gate runs Biome, TypeScript checks, automated tests, a production build, a CLI smoke test, and an npm package dry run. CI covers Node.js 20, 22, and 24.

Read CONTRIBUTING.md before opening a pull request and SECURITY.md before reporting a vulnerability.

License and Disclaimer

Cuebook CLI is available under the MIT License.

Cuebook provides market information, structured reasoning, and simulated tools. It does not provide investment advice. A Cue is not a recommendation to trade, and every decision remains yours.