options-chain-mcp

Read-only MCP server for options research. Pluggable data provider — currently supports Tradier and Alpaca.

npx -y options-chain-mcp

> You must bring your own market data credentials. Unlike a server that wraps a

> free public API, this one talks to a brokerage data provider on your behalf, so it

> needs a `TRADIER_TOKEN`, or an `ALPACA_API_KEY_ID` + `ALPACA_SECRET_KEY`, in its

> environment. Free sandbox/paper accounts work fine — see

> Choosing a data provider. Started without credentials,

> the server exits immediately and prints which variable is missing.

Overview

This Model Context Protocol (MCP) server gives AI assistants the tools to research options, without any ability to place trades:

• `find-options-chain` — chain for a symbol + expiration, filtered to options with real volume/bid/ask and strikes within a percentage of spot. Automatically trims to significant strikes to keep the payload LLM-friendly.
• `find-option-expirations` — valid expiration dates for an underlying.
• `get-quote` — latest quote for a stock symbol or a single OCC option contract. Includes Greeks + IV when the provider supports them (Alpaca does; Tradier requires a chain lookup).
• `historical-prices` — OHLCV bars for a stock or OCC option over any range and interval.

The server runs two ways:

• Locally over stdio for Claude Desktop
• Remotely on Cloudflare Workers with OAuth 2.1, for Claude.ai and other MCP clients that speak the remote-connector protocol

Please note:

• Requires API credentials for whichever provider you use (free paper/sandbox accounts work)
• Market data on free plans is typically 15-min delayed
• Intended for informational purposes only

Users can run queries using natural language.

Why this server (instead of the official Tradier or Alpaca MCP)

Built for LLM context budgets. A typical underlying has hundreds of strikes across dozens of expirations. Calling a raw `get_option_chain` from the official Alpaca server returns *all of them* — every dead far-OTM strike, every penny-bid contract, every field the API exposes. That payload eats thousands of tokens per call and forces the model to filter the noise itself. This server filters server-side:

• Strikes are pre-filtered to a configurable percentage band around spot
• Dead contracts are dropped (`volume > 0 OR open_interest > 0` and `bid/ask > $0.10`)
• A "significant strikes" pass keeps round-numbered strikes at distance and finer-grained strikes near the money — mimicking how a human trader actually reads a chain
• Only the fields a research workflow needs are returned (no exchange codes, no raw timestamps, no boilerplate)

In practice a NVDA chain comes back as ~15 strikes instead of ~400 — roughly 20–40× fewer tokens per call, leaving room for actual analysis in the conversation.

Other things going for it:

• Read-only by design. No `place_order`, no `close_position`, no `exercise_options_position`. Point an LLM at it without worrying about hallucinated trades.
• Provider-pluggable. Tradier and Alpaca behind one identical tool surface. Swap with one env var; if one provider's data goes stale or the account expires, fall over to the other without changing prompts or client config.
• Remote OAuth deployment included. Works from claude.ai web (and any other OAuth-aware MCP client), not just locally-connected Claude Desktop. The official Alpaca server is stdio-only.

Sample Output

Q: What are the highlights of the SPY options chain for two weeks out?

A: I'll check the current SPY options chain for two weeks out from today.

View Result from find-options-chain from options-chain (local)

{
  "symbol": "SPY",
  "expiration": "2025-03-28"
}

Now that I have the SPY options chain for March 28, 2025 (two weeks out), I'll highlight the key information:

SPY Options Chain Highlights (March 28, 2025 Expiration)

Current Market Context

Current SPY price appears to be around $565-566 based on the at-the-money options

Call Options Highlights

1. Highest Volume:

2. Highest Open Interest:

3. Notable Activity:

Put Options Highlights

1. Highest Volume:

2. Highest Open Interest:

3. Notable Activity:

Implied Volatility Indicators

Options Skew

Installation

Requires Node.js 20 or newer. No install step is

needed — `npx` fetches the server on first run. You do need credentials for one of the

two data providers; see Choosing a data provider.

There are two ways to run this server, and they authenticate differently:

Local setup is covered directly below; remote setup is under

Running on Cloudflare Workers.

Claude Code

claude mcp add options-chain --env TRADIER_TOKEN=your_token -- npx -y options-chain-mcp

Any other MCP client

The server speaks MCP over STDIO. Run it with `npx -y options-chain-mcp`, or install it

globally with `npm install -g options-chain-mcp` and run `options-chain-mcp`, with the

provider credentials present in the environment.

Development

npm install        # install dependencies
npm run dev:stdio  # run the stdio server from source
npm run build      # compile TypeScript to build/
npm run typecheck  # type-check both the stdio and Workers configs
npm run dev        # run the Cloudflare Workers version locally
npm run deploy     # deploy the Workers version

Tool definitions live in `src/tools.ts` and are shared by both entry points:

`src/index.ts` (stdio) and `src/worker.ts` (Cloudflare Workers). Provider-specific

code lives in `src/providers/`.

`build/` is generated and not checked in — run `npm run build` before pointing Claude

Desktop at a local build.

Choosing a data provider

The server supports two providers. Set the credentials for whichever you want and (optionally) `DATA_PROVIDER` to pick explicitly. If `DATA_PROVIDER` is unset, Alpaca is used when both Alpaca keys are set, otherwise Tradier.

See `sample.env` for optional overrides (feed selection, base-URL overrides for live accounts).

Provider differences worth knowing

The chain filter treats `volume > 0 OR open_interest > 0` as "real market interest," so dead strikes get dropped on either provider. When you see `"volume": null` in an Alpaca response, that means *the provider doesn't report it* — not that the contract is inactive. Use `open_interest` for liquidity assessments on Alpaca.

Connecting with Claude Desktop (stdio)

1. Open your Claude Desktop configuration at:

2. Add the server configuration (using whichever provider you want):

{
    "mcpServers": {
        "options-chain": {
            "command": "npx",
            "args": ["-y", "options-chain-mcp"],
            "env": {
                "TRADIER_TOKEN": "your_tradier_sandbox_token"
            }
        }
    }
}

To run a local build instead, use `"command": "node"` with

`"args": ["/full/path/to/options-chain/build/index.js"]` after `npm run build`.

Or for Alpaca:

"env": {
    "ALPACA_API_KEY_ID": "your_key_id",
    "ALPACA_SECRET_KEY": "your_secret"
}

3. Close/Quit then restart Claude Desktop

Once you restart you should see a small hammer icon in the lower right corner of the textbox. If you hover over the icon you'll see the number of MCP tools available.

> The legacy lowercase `token` env var is still accepted for backward compatibility with older configs.

Running on Cloudflare Workers (remote, OAuth 2.1)

The Worker entrypoint (`src/worker.ts`) exposes the same tools over MCP's SSE and Streamable HTTP transports, wrapped in an OAuth 2.1 provider. Claude.ai (web and desktop) discovers the endpoints automatically via Dynamic Client Registration.

Requirements

• A Cloudflare account on any paid Workers plan (Durable Objects are used for MCP session state)
• Wrangler authenticated: `npx wrangler login`
• A KV namespace bound as `OAUTH_KV` (create with `npx wrangler kv namespace create OAUTH_KV` and paste the ID into `wrangler.jsonc`)

Configure secrets

For Tradier:

npx wrangler secret put TRADIER_TOKEN

For Alpaca:

npx wrangler secret put ALPACA_API_KEY_ID
npx wrangler secret put ALPACA_SECRET_KEY
# optional:
npx wrangler secret put DATA_PROVIDER            # "alpaca" or "tradier"

And the auth passcode that gates the consent page:

npx wrangler secret put APPROVE_PASSCODE         # e.g. `openssl rand -base64 18`

For local dev, put the same keys in a `.dev.vars` file at the repo root (gitignored).

Deploy

npm run dev       # local dev server with hot reload
npm run deploy    # publish to ..workers.dev

Connect Claude to the deployed server

In Claude.ai → Settings → Connectors → Add custom connector:

1. URL: `https://.workers.dev/sse` (or `/mcp` for Streamable HTTP).

2. Leave client ID/secret blank — the server advertises Dynamic Client Registration.

3. Save and click connect. Claude opens a consent page; enter the `APPROVE_PASSCODE` you set above.

4. You'll be redirected back, authorized. Tokens refresh for 30 days.

Auth upgrade path

For multi-user access or SSO, put Cloudflare Access in front of the Worker route. The OAuth flow still works for the MCP client; Access just adds a second layer for the human consent page.

Troubleshooting

If Claude Desktop cannot find `npx`, provide its full path (on macOS, typically

`/usr/local/bin/npx` or `/opt/homebrew/bin/npx`). The same applies to `node` if you are

running a local build.

If the server does not appear at all, check Claude Desktop's logs — the server now

writes a specific reason to stderr (for example, missing provider credentials) instead

of exiting silently.