# Options Chain

> Option Chain MCP server

- **Type:** MCP server
- **Install:** `agentstack add mcp-blake365-options-chain`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [blake365](https://agentstack.voostack.com/s/blake365)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [blake365](https://github.com/blake365)
- **Source:** https://github.com/blake365/options-chain

## Install

```sh
agentstack add mcp-blake365-options-chain
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# options-chain-mcp
Read-only MCP server for options research. Pluggable data provider — currently supports [Tradier](https://documentation.tradier.com/brokerage-api) and [Alpaca](https://docs.alpaca.markets).

## 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)

```json
{
  "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:
 - $590 calls with 217 contracts traded
 - $600 calls with 174 contracts traded
 - $571 calls with 130 contracts traded

2. Highest Open Interest:
 - $600 calls: 8,299 contracts
 - $590 calls: 6,591 contracts
 - $605 calls: 4,676 contracts
 - $580 calls: 4,596 contracts

3. Notable Activity:
 - Far out-of-the-money calls ($590-$600) showing significant volume, suggesting some traders are positioning for potential upside movement
 - The $590 calls (priced at $1.07-$1.09) have high volume and open interest

### Put Options Highlights

1. Highest Volume:
 - $500 puts with 217 contracts traded
 - $460 puts with 160 contracts traded
 - $510 puts with 163 contracts traded

2. Highest Open Interest:
 - $525 puts: 79,196 contracts (extremely high)
 - $530 puts: 7,060 contracts
 - $550 puts: 4,883 contracts
 - $570 puts: 4,337 contracts

3. Notable Activity:
 - The massive open interest in $525 puts is striking, suggesting a significant hedging position
 - Overall put activity shows traders protecting against downside risk

### Implied Volatility Indicators

 - Looking at the pricing, implied volatility appears moderate
 - The put-call ratio based on open interest is skewed toward puts, suggesting market participants are hedging against downside risk

### Options Skew

 - There's higher open interest in OTM puts than OTM calls, indicating traders are more concerned about downside protection than upside speculation

## Installation

Installing this might be tricky if you're not familiar with Node.js and the MCP protocol.

1. Install [Node.js](https://nodejs.org/en/download)
2. Clone this repository to a folder on your local machine
3. The server is already built so you can skip the build step.

### Extra Steps

If you want to make changes to the server you can do so by editing the `src/index.ts` file.
- Run `npm install` to install dependencies
- Run `npm run build` to build the server
- Quit and restart Claude Desktop after making changes

## 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.

| Provider | Env vars | Notes |
| --- | --- | --- |
| Tradier sandbox | `TRADIER_TOKEN` | 15-min delayed. Sandbox tokens expire — [dashboard](https://sandbox.tradier.com) lets you regenerate. |
| Alpaca | `ALPACA_API_KEY_ID`, `ALPACA_SECRET_KEY` | Paper account key works fine. Free `indicative` options feed includes Greeks + IV. |

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

### Provider differences worth knowing

| Field | Tradier | Alpaca |
| --- | --- | --- |
| `volume` (per option) | Daily total | `null` — not exposed by the snapshot endpoint |
| `open_interest` | Returned natively | Fetched from the trading API's contracts endpoint and merged in |
| Greeks + IV on free tier | Yes (when `greeks=true`) | Yes (free `indicative` feed) |

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:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add the server configuration (using whichever provider you want):
```json
{
    "mcpServers": {
        "options-chain": {
            "command": "node",
            "args": [
                "/Full/Route/to/Folder/options-chain/build/index.js"
            ],
            "env": {
                "TRADIER_TOKEN": "your_tradier_sandbox_token"
            }
        }
    }
}
```

Or for Alpaca:
```json
"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:
```bash
npx wrangler secret put TRADIER_TOKEN
```

For Alpaca:
```bash
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:
```bash
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

```bash
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 you get errors when running the server you may need to provide the full path to the `node` command. For example, on macOS: `/usr/local/bin/node`

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [blake365](https://github.com/blake365)
- **Source:** [blake365/options-chain](https://github.com/blake365/options-chain)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-blake365-options-chain
- Seller: https://agentstack.voostack.com/s/blake365
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.