Robinhood For Agents README

robinhood-for-agents

An MCP server that lets your AI agent read and trade your Robinhood account, in one of two modes:

• Standard mode (default): Robinhood's official hosted Trading MCP, 77 tools; orders reach your Agentic account.
• Web mode: the unofficial web API robinhood.com uses, 59 tools, every brokerage account.

Also included: a TypeScript client library (82 async methods) and a trading skill for agent apps that support skills. Works with Claude Code, Codex, Cursor, Antigravity, Hermes, and any other MCP client; OpenClaw uses the skill.

Quick start

1. Run the installer. Needs Bun v1.3+.

   bashCopy

   bunx robinhood-for-agents install
   

   It detects your agent apps and asks which to configure and whether to add web mode, then registers the server with a generated ROBINHOOD_TOKEN_KEY (reused on re-runs) and copies the trading skill into each app that supports skills. Manual setup instead: npx -y add-mcp "bunx robinhood-for-agents" -g -n robinhood-for-agents --env "ROBINHOOD_TOKEN_KEY=<32-byte base64 key>" plus npx skills add kevin1chun/robinhood-for-agents.

   Other clients:

   OpenClaw

   Web mode only: the skill calls the client library through bun, with no MCP server. bunx robinhood-for-agents install covers it when ~/.openclaw exists (as "OpenClaw (skill only)": the skill plus robinhood-for-agents in ~/.openclaw/workspace). Alternative:

   bashCopy

   clawhub install robinhood-for-agents
   

   Hermes

   Add to ~/.hermes/config.yaml, keeping the entries for the modes you use, then run /reload-mcp:

   yamlCopy

   mcp_servers:
     robinhood-for-agents:
       command: "bunx"
       args: ["robinhood-for-agents"]
       env:
         ROBINHOOD_TOKEN_KEY: "<any 32-byte base64 key, e.g. from the installer's config entry>"
     robinhood-web:
       command: "bunx"
       args: ["robinhood-for-agents", "--mode", "web"]
   

2. Restart the app and ask your agent to "log in to Robinhood"; approve once in the browser. Then prompt it: "show my portfolio".

Choosing a mode

Use standard mode unless you need something only web mode has. It is the surface Robinhood supports for agents: the 76 official tools, with Robinhood's own titles, descriptions, schemas, and annotations, each call relayed unchanged to agent.robinhood.com/mcp/trading. Orders reach your Agentic account only; other accounts are read-only. Web mode trades that for reach: it calls the web API robinhood.com itself uses, serves every brokerage account, and backs the client library, but Robinhood does not sanction it for agents.

25 tools exist only in standard mode, 8 only in web mode; the Mode column in Tools says which, and docs/MODES.md has the full comparison. To run both, register both entries, robinhood-for-agents and robinhood-web. Tool names match, so your agent tells them apart by entry; the credentials are separate.

Install

Prerequisites: Bun v1.3+ and a Robinhood account. Standard mode needs ROBINHOOD_TOKEN_KEY (the installer sets it), and its sign-in opens your browser with the macOS open command. Web mode needs Google Chrome for login (playwright-core, channel: "chrome"; no bundled browser, Brave/Chromium fallback, or BROWSER_PATH override).

Setup commands

bunx robinhood-for-agents install      # pick apps, register the server, copy the skill; -y takes every detected app, standard mode only
bunx robinhood-for-agents login        # web-mode Chrome login outside an MCP client
bunx robinhood-for-agents login --export   # also writes ./tokens.enc for Docker

install registers entries through the add-mcp library (supported apps: npx add-mcp list-agents) and copies the skill with the skills CLI. It overwrites existing robinhood-for-agents/robinhood-web entries and keeps the ROBINHOOD_TOKEN_KEY already in them.

From source

git clone https://github.com/kevin1chun/robinhood-for-agents.git
cd robinhood-for-agents
bun install
bun bin/robinhood-for-agents.ts   # standard mode; add --mode web for web mode

To register a checkout, pass "bun run /path/to/checkout/bin/robinhood-for-agents.ts" as the add-mcp target in the manual setup line.

What each client gets:

Sign in

• Standard: ask your agent to run robinhood_official_login, then approve once in the browser it opens. The browser must reach the server's 127.0.0.1 callback. Until then, every standard-mode tool answers an error naming the login tool. The credential is stored as official-mcp.enc (AES-256-GCM under ROBINHOOD_TOKEN_KEY), never in the keychain.
• Web: say "setup robinhood" or call robinhood_browser_login, then log in to Robinhood in Chrome with your credentials and MFA. The token capture is a passive network intercept that never touches the page. The session is cached in the OS keychain (or the encrypted file named by ROBINHOOD_TOKENS_FILE) and renews a day before expiry and on any 401; a long idle gap lapses it and needs a new login. robinhood_check_session probes the API and answers logged_in, expired, unknown, or not_authenticated.
• Storage, rotation, and failure modes: docs/SECURITY.md. Mechanics: docs/ARCHITECTURE.md.

What you can do

"Buy 1 50-delta SPX call expiring tomorrow"

The robinhood-for-agents skill (Claude Code and OpenClaw; clawhub install robinhood-for-agents from ClawHub) adds guided workflows. With Claude Code it drives whichever MCP entry you registered, so standard-only tools need robinhood-for-agents; standalone it uses the client library, which is web mode only.

In skills/robinhood-for-agents/, SKILL.md routes to domain files (portfolio.md, trade.md, …) and the client-api.md reference, loaded on demand. More examples: docs/USE_CASES.md.

Tools

Names and input schemas are the official ones, prefixed robinhood_ (parity table). In standard mode each tool also carries Robinhood's title, description, output schema, and annotations verbatim from docs/official-mcp-tools.json. The hosted server's rate limit: measured here. Mode: standard or web = only in that mode; both = both modes.

Placing orders

Both modes run review → confirm → place. robinhood_review_equity_order simulates the order (live quote plus Robinhood's price collar) and places nothing. Show the result, get explicit confirmation, then call robinhood_place_equity_order. The client-side checks below run in web mode only; standard mode relays the call for Robinhood to validate.

Side — buy, sell, or sell_short:

sell only closes a long; selling shares you don't hold fails with Not enough shares to sell. sell_short carries unlimited loss, so confirm the user meant a short. Shorts also need gfd and the regular or extended session, not the 24 Hour Market.

Trading session — market_hours defaults to regular_hours, as in the official tool:

An order tagged to the wrong session queues for the next open instead of executing, which looks like success. Name the session outside regular hours; robinhood_get_market_hours says which is live. See examples/short-selling.ts, trade.md, and docs/ARCHITECTURE.md.

Client library

import { RobinhoodClient } from "robinhood-for-agents";

const client = new RobinhoodClient();
await client.restoreSession();

const quotes = await client.getQuotes("AAPL");
const portfolio = await client.buildHoldings();

Web mode only; there is no client-library path to the hosted MCP. All 82 methods are async, and account-scoped ones take accountNumber. Reference, including EncryptedFileTokenStore and direct-accessToken construction: client-api.md.

Docker and headless

Without a keychain or browser, both modes keep their credential in an encrypted file under ROBINHOOD_TOKEN_KEY and sign in on the host.

• Standard: official-mcp.enc lives beside ROBINHOOD_TOKENS_FILE, so mount the directory, not the file (docs/DOCKER.md).
• Web: run bunx robinhood-for-agents login --export on the host. It exports ./tokens.enc, copies the key to the clipboard, and prints the env vars, including ROBINHOOD_MODE=web (docs/DOCKER.md).

Keep the mount read-write and use one process per token file: refresh tokens are single-use, and a failed write-back logs CRITICAL to stderr and strands the container on restart. Encryption stops casual disk access, not an agent with shell access that can read the key, so run only agents you trust (docs/SECURITY.md).

Safety

• Fund transfers, bank operations, and bulk cancel are absent by design, not gated.
• Every order is confirmed with the user; the skill enforces review → confirm → place.
• Account, symbol, side, and order type are explicit; time_in_force and market_hours default to gfd and regular_hours, as in the official tools.
• A short needs the explicit sell_short side, so a mis-parsed "sell" can never open one.
• Order writes resolve the symbol by exact match, never a fuzzy search.
• Standard-mode orders are relayed to Robinhood's hosted MCP and reach the Agentic account only.
• The standard-mode credential lives only in an encrypted file; web-mode tokens live in the OS keychain or an AES-256-GCM file.
• No real PII in this repo; examples use placeholders like "ACCOUNT_ID".
• Risk matrix: docs/ACCESS_CONTROLS.md. Threat model: docs/SECURITY.md. Multi-agent identity and gateway auth: docs/AGENT-IDENTITY.md, docs/GATEWAY-AUTH.md.

Development

bun install
bun run typecheck              # tsc --noEmit
bun run check                  # Biome lint + format
npx vitest run                 # all tests — vitest, not `bun test`

Integration tests (read-only, real API, not in CI): bunx robinhood-for-agents login, then bun run test:integration. Design: docs/ARCHITECTURE.md. Adding tools and skills: docs/CONTRIBUTING.md.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Robinhood Markets, Inc. "Robinhood" is a trademark of Robinhood Markets, Inc. This software interacts with Robinhood's services through publicly accessible interfaces but is an independent, third-party tool.

USE AT YOUR OWN RISK. This software enables AI agents to read data from and place orders on your Robinhood brokerage account. Automated and AI-assisted trading carries inherent risks, including but not limited to:

• Unintended order execution due to AI misinterpretation
• Financial losses from erroneous trades
• Stale or inaccurate market data
• Software bugs or unexpected behavior

You are solely responsible for all activity on your brokerage account, whether initiated manually or through this software. The authors and contributors assume no liability for any financial losses, damages, or other consequences arising from the use of this software. Review all AI-proposed actions before confirming, and never grant unsupervised trading authority to any automated system.

This software is provided "as is" without warranty of any kind. See LICENSE for full terms.

A note from the maintainer

I'm a solo developer. I built this for myself, I use it every day, and I keep it up to date so anyone else can share the joy of it. If it saves you time or makes trading more fun, a coffee helps me keep pace with changes to Robinhood's API and official MCP, and keep adding new tools:

A star on the repo helps too, and issues and pull requests are always welcome.

License

MIT — see LICENSE.