robinhood-for-agents

Robinhood for AI agents — MCP server with 49 tools + TypeScript client library.

• 49 MCP tools for any MCP-compatible AI agent
• Unified trading skill for guided workflows (Claude Code, OpenClaw, ClawHub)
• TypeScript client library (70+ async methods) for programmatic use
• Pluggable token storage — OS keychain (default) or encrypted file (Docker/headless)

Compatible with Claude Code, Codex, OpenClaw, and any MCP-compatible agent.

Prerequisites

• Bun v1.3+
• Google Chrome for login (driven by playwright-core via channel: "chrome", no bundled browser). Chrome must be installed — there's no Brave/Chromium fallback or BROWSER_PATH override yet.
• A Robinhood account

Quick Start

Guided setup (recommended)

# Requires Bun runtime — see Prerequisites
npx robinhood-for-agents onboard

The interactive setup detects your agent, registers the MCP server, installs skills (where supported), and walks you through Robinhood login. It handles both local and Docker deployments — just pick "This machine" or "Docker container / remote host" when prompted.

You can also specify your agent directly:

npx robinhood-for-agents onboard --agent claude-code
npx robinhood-for-agents onboard --agent codex
npx robinhood-for-agents onboard --agent openclaw

From source

git clone https://github.com/kevin1chun/robinhood-for-agents.git
cd robinhood-for-agents
bun install
bun run onboard

Manual setup

# Register MCP server (global — available in all projects)
claude mcp add -s user robinhood-for-agents -- bunx robinhood-for-agents

# Install skills (per-project, optional)
cd your-project
npx robinhood-for-agents install --skills

From a source checkout, register the server as claude mcp add -s user robinhood-for-agents -- bun run /path/to/checkout/bin/robinhood-for-agents.ts instead.

Restart Claude Code to pick up the changes. Claude Code supports the unified trading skill in addition to the 49 MCP tools — see Skill.

codex mcp add robinhood-for-agents -- bunx robinhood-for-agents

From a source checkout, use -- bun run /path/to/checkout/bin/robinhood-for-agents.ts instead.

Restart Codex to pick up the changes. Codex uses all 49 MCP tools directly.

Via ClawHub (recommended):

clawhub install robinhood-for-agents

Via onboard CLI:

robinhood-for-agents onboard --agent openclaw

Both install the unified robinhood-for-agents skill to ~/.openclaw/workspace/skills/. No MCP server required — the skill uses the TypeScript client API directly via bun.

Add to your MCP client's config (e.g. ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "robinhood-for-agents": {
      "command": "bunx",
      "args": ["robinhood-for-agents"]
    }
  }
}

From a source checkout, use "command": "bun", "args": ["run", "/absolute/path/to/checkout/bin/robinhood-for-agents.ts"] instead.

Example

"Buy 1 50-delta SPX call expiring tomorrow"

Authenticate

Start your agent and say "setup robinhood" (or call robinhood_browser_login directly). Your browser will open to the real Robinhood login page — log in with your credentials and MFA. The session is cached in your OS keychain and auto-refreshes when the access token expires (via the stored refresh token), so you stay logged in for roughly a week before a browser re-login is needed.

MCP Tools (49)

All 49 tools work with every MCP-compatible agent.

| Tool | Description | |------|-------------| | robinhood_browser_login | Authenticate via Chrome browser | | robinhood_check_session | Check if cached session is valid | | robinhood_get_portfolio | Portfolio: positions, P&L, equity, cash, buying power | | robinhood_get_equity_positions | Raw equity positions (shares, avg price) | | robinhood_get_equity_tax_lots | Open tax lots for one equity holding (cost basis, term, open date) | | robinhood_get_accounts | List all brokerage accounts | | robinhood_get_account | Account details and profile | | robinhood_get_stock_quote | Stock quotes and fundamentals | | robinhood_get_fundamentals | Fundamentals: float, shares outstanding, valuation, profile | | robinhood_get_short_interest | Daily short-interest estimate (% of float, with bounds) | | robinhood_get_historicals | OHLCV price history | | robinhood_get_equity_price_book | Level-2 price book (bid/ask depth) | | robinhood_get_equity_tradability | Tradability flags (fractional, short-selling, per-account) | | robinhood_get_earnings_results | Earnings for a symbol (EPS estimate vs. actual) | | robinhood_get_earnings_calendar | Market-wide earnings calendar for a day window | | robinhood_get_news | News, analyst ratings, earnings | | robinhood_get_movers | Market movers and popular stocks | | robinhood_get_indexes | Tradable market indexes (SPX, NDX, VIX, …) | | robinhood_get_index_quotes | Current values for index symbols | | robinhood_get_options | Options chain with greeks | | robinhood_get_option_positions | Open option positions (per-leg or by strategy) | | robinhood_get_option_orders | Option order history | | robinhood_get_option_historicals | Historical OHLC for a specific option contract | | robinhood_get_crypto | Crypto positions and quotes | | robinhood_review_equity_order | Simulate a stock order before placing (price-collar check, live quote) | | robinhood_review_option_order | Simulate an option order before placing (per-leg data, collateral) | | robinhood_place_stock_order | Place stock orders (market/limit/stop/trailing) | | robinhood_place_option_order | Place option orders | | robinhood_place_crypto_order | Place crypto orders | | robinhood_get_orders | View order history | | robinhood_cancel_order | Cancel an order by ID | | robinhood_get_order_status | Get status of a specific order by ID | | robinhood_search | Search stocks or browse categories | | robinhood_get_watchlists | List your own watchlists (with list ids) | | robinhood_get_watchlist_items | Items of a watchlist (enriched with symbols) | | robinhood_get_popular_watchlists | Robinhood-curated lists to follow | | robinhood_get_option_watchlist | Your options watchlist — single-leg option contracts | | robinhood_create_watchlist | Create a new watchlist (confirm first) | | robinhood_update_watchlist | Rename / re-describe a watchlist (confirm first) | | robinhood_add_to_watchlist | Add symbols / indexes / crypto to a list (confirm first) | | robinhood_remove_from_watchlist | Remove items from a list (confirm first) | | robinhood_follow_watchlist | Follow a Robinhood-curated list (confirm first) | | robinhood_unfollow_watchlist | Unfollow a curated list (confirm first) | | robinhood_add_option_to_watchlist | Add long single-leg option contracts to the options watchlist (confirm first) | | robinhood_remove_option_from_watchlist | Remove single-leg option contracts from the options watchlist (confirm first) | | robinhood_get_scans | List your saved scanners (screeners) | | robinhood_get_scanner_filter_specs | Filter vocabulary for building scans (RSI/MACD/fundamentals/…) | | robinhood_get_realized_pnl | Realized P&L over a window, bucketed (computed FIFO; equity + crypto) | | robinhood_get_pnl_trade_history | Per-trade realized P&L (computed FIFO; equity + crypto) |

Skill

A single unified skill (robinhood-for-agents) provides guided workflows for auth, portfolio, research, trading, and options. Available on ClawHub and supported by Claude Code and OpenClaw.

# Install via ClawHub
clawhub install robinhood-for-agents

| Domain | Example Triggers | |--------|-----------------| | Setup | "setup robinhood", "connect to robinhood" | | Portfolio | "show my portfolio", "my holdings" | | Research | "research AAPL", "analyze TSLA" | | Trading | "buy 10 AAPL", "sell my position" | | Options | "show AAPL options", "SPX calls" |

Dual-mode: The skill works with MCP tools (Claude Code) or standalone via the TypeScript client API and bun (OpenClaw, any agent with shell access). No MCP server required.

The skill uses progressive disclosure — SKILL.md is the compact router, with domain-specific files (portfolio.md, trade.md, etc.) and a full client-api.md reference loaded on demand.

Agent Compatibility

| Feature | Claude Code | Codex | OpenClaw | Other MCP | |---------|:-----------:|:-----:|:--------:|:---------:| | 49 MCP tools | Yes | Yes | — | Yes | | Trading skill | Yes | — | Yes | — | | ClawHub install | — | — | Yes | — | | onboard setup | Yes | Yes | Yes | — | | Browser auth | Yes | Yes | Yes | Yes |

Client Library (standalone)

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

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

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

Docker / Headless Deployment

When deploying in Docker, headless servers, or cloud environments where no OS keychain is available, use the EncryptedFileTokenStore:

Setup

The guided setup handles Docker — pick "Docker container / remote host" when prompted:

npx robinhood-for-agents onboard

This will:

1. Open Chrome for Robinhood login (on the host)
2. Encrypt tokens and export to ./tokens.enc
3. Print the encryption key and env vars to set in your container

Manual setup

# 1. Login on the host
npx robinhood-for-agents onboard

# 2. In your container, set env vars:
export ROBINHOOD_TOKENS_FILE=/path/to/tokens.enc
export ROBINHOOD_TOKEN_KEY=<base64-key-from-step-1>

# docker-compose.yml
services:
  agent:
    image: your-agent-image
    volumes:
      - ./tokens.enc:/app/tokens.enc:rw
    environment:
      ROBINHOOD_TOKENS_FILE: "/app/tokens.enc"
      ROBINHOOD_TOKEN_KEY: "${ROBINHOOD_TOKEN_KEY}"

Token refresh writes re-encrypted tokens back to the file automatically.

Security warning: The encrypted file protects against casual disk access (image leaks, accidental exposure) but NOT against a malicious agent with shell access in the container — it can read the env var and decrypt. Only run agents you trust. See docs/SECURITY.md for the full threat model.

Safety

• Pluggable token storage — KeychainTokenStore (OS keychain, default) or EncryptedFileTokenStore (AES-256-GCM, for Docker/headless). See SECURITY.md for the threat model.
• Fund transfers and bank operations are blocked — never exposed
• Bulk cancel operations are blocked
• All order placements require explicit parameters (no dangerous defaults)
• Skills always confirm with the user before placing orders
• See ACCESS_CONTROLS.md for the full risk matrix
• For multi-agent deployments, see AGENT-IDENTITY.md for agent identity verification and per-tool authorization patterns

Authentication

Login: Call robinhood_browser_login (MCP) or say "setup robinhood" (skills) to open Chrome. Log in normally with your credentials and MFA. Playwright passively intercepts the OAuth token response — it never clicks buttons or fills forms.

Token storage uses pluggable TokenStore adapters:

| Store | When to use | Config | |---|---|---| | KeychainTokenStore (default) | Local dev, macOS/Linux with desktop | Nothing — works out of the box | | EncryptedFileTokenStore | Docker, headless servers, CI, cloud | Set ROBINHOOD_TOKENS_FILE + ROBINHOOD_TOKEN_KEY env vars | | Direct accessToken | Serverless, testing, short-lived scripts | Pass accessToken to constructor or set ROBINHOOD_ACCESS_TOKEN env var |

How it works: restoreSession() loads tokens from the configured TokenStore, injects Authorization: Bearer headers directly into API requests, and registers automatic token refresh on 401.

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

// Default: KeychainTokenStore
const client = new RobinhoodClient();

// Docker/headless: EncryptedFileTokenStore (auto-detected from ROBINHOOD_TOKENS_FILE env)
const client = new RobinhoodClient({ tokenStore: new EncryptedFileTokenStore() });

// Direct token (no refresh)
const client = new RobinhoodClient({ accessToken: "..." });

See docs/ARCHITECTURE.md for the full auth flow and docs/SECURITY.md for the threat model.

Development

bun install                    # Install deps
bun run typecheck              # tsc --noEmit
bun run check                  # Biome lint + format
npx vitest run                 # Run all tests

Integration tests (verify local setup)

Integration tests hit the real Robinhood API (read-only). Use them to confirm your local dev environment is working end-to-end.

# 1. Login (opens Chrome — one-time)
npx robinhood-for-agents onboard

# 2. Run integration tests
bun run test:integration

These are excluded from CI and the default test commands since they require real credentials.

Architecture

See docs/ARCHITECTURE.md for full system design, authentication flow, HTTP pipeline, and exception hierarchy.

Contributing

See docs/CONTRIBUTING.md for how to add new tools, create skills, and run tests.

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.

License

MIT — see LICENSE.