MCP 服务器

Cuebook MCP Server

Provides market intelligence including asset search, market state, cues, events, and paper trading via the Model Context Protocol.

README

<h1 align="center">Cuebook CLI — market intelligence for humans and AI agents</h1>

<p align="center"> The official command-line interface for Cuebook. Bring sourced Cues, market context, catalysts, and safe paper-trading workflows into Codex, Claude Code, OpenClaw, scripts, or any terminal. </p>

<p align="center"> <a href="#quick-start">Quick Start</a> · <a href="#why-cuebook-cli">Why Cuebook CLI</a> · <a href="#commands">Commands</a> · <a href="#agent-workflows">Agent Workflows</a> · <a href="#write-safety">Write Safety</a> · <a href="#authentication">Authentication</a> · <a href="#troubleshooting">Troubleshooting</a> </p>

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.

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

What an agent needs	How Cuebook CLI answers it
A surface it can learn at runtime	`cuebook tools list` returns the current Tool catalog
Commands it can compose without guessing	Focused verbs cover assets, market state, Cues, diagnostics, and paper trading
Output it can parse reliably	Global `--json` returns structured results and errors
Secure account access	OAuth 2.1, PKCE, and explicit browser approval
Safe behavior around new capabilities	Known reads run normally; writes and unknown Tools require `--confirm`
Network resilience without duplicate actions	Transient reads can retry; write calls never retry automatically

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

Command	Purpose
`cuebook auth login`	Connect the CLI to your Cuebook account
`cuebook auth status`	Check the current connection
`cuebook auth logout`	Remove local OAuth credentials
`cuebook connections`	Manage connected Agents
`cuebook tools list`	Discover available Tools
`cuebook assets search <query>`	Find an asset and its canonical ticker
`cuebook market state <tickers...>`	Read the latest market snapshot
`cuebook cues latest`	Read the newest Cues
`cuebook cues latest --asset <ticker>`	Read Cues for one asset
`cuebook paper portfolio`	Inspect your virtual portfolio
`cuebook paper preview <ticker> ...`	Preview a paper order
`cuebook call <tool>`	Call any available Tool
`cuebook doctor`	Diagnose authentication and connectivity

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

Area	Capabilities
Assets and market	Asset search, market snapshots, historical candles
Cues and reasoning	Asset Cues, global timeline, themes, details, reasoning graphs
Events and research	Events, market briefings, news clusters, search, filings, disclosures
Positioning and catalysts	Positioning, market calendar, prediction markets, settlements
Paper trading	Virtual portfolio, order preview, paper orders, position closing, order history

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

Exit code	Meaning
`0`	Command completed successfully
`1`	The command failed
`2`	Authorization or explicit write confirmation is required

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:

Known read operations run normally.
A write-capable or newly introduced Tool requires --confirm.
Confirmed writes are sent once and never retried automatically.
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

Variable	Purpose
`CUEBOOK_MCP_URL`	Use a different MCP endpoint
`CUEBOOK_ACCESS_TOKEN`	Use an externally managed Bearer Token
`CUEBOOK_CONFIG_DIR`	Choose the local credential directory
`CUEBOOK_DEBUG=1`	Print stack traces for CLI errors

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

Troubleshooting

Start with:

cuebook doctor

Symptom	Resolution
`Cuebook authorization is required`	Run `cuebook auth login` and approve the request
Connection limit reached	Run `cuebook connections` and disconnect an unused Agent
OAuth callback port is busy	Run `cuebook auth login --callback-port 53683`
Persistent `fetch failed`	Check TLS, proxy, VPN, and network access, then run `cuebook doctor`
Local logout did not free a slot	Disconnect the connection from `cuebook connections`

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.