finra-mcp-server

A Model Context Protocol (MCP) server that exposes the FINRA Query API as a set of tools. It lets MCP-capable clients (Claude Desktop, Claude Code, and other MCP hosts) query FINRA's public regulatory and market datasets — TRACE corporate bond trades, OTC equity summaries, short interest, firm registration data, and more — in natural language.

The server handles OAuth2 authentication, token caching, request shaping, and pagination, and ships with a local catalog of datasets so a model can discover what's available before issuing a query.

What it does

FINRA publishes a large family of datasets through a single Query API surface:

/data/group/{group}/name/{dataset}

Each dataset supports field projection, comparison filters, date-range filters, IN-list (domain) filters, sorting, and pagination. This server wraps that API with:

• OAuth2 client-credentials flow — fetches and caches a bearer token, refreshing automatically before expiry.
• A generic query tool (`finra_query`) that exposes the full filtering surface of the Query API.
• A local dataset catalog so the model can discover valid `group`/`dataset` combinations without guessing.
• Curated convenience tools for the most common datasets (TRACE bonds, short interest, OTC weekly summary, firm profile) that map friendly arguments (CUSIP, symbol, date range, CRD number) onto the underlying query shape.

Tools

`finra_query` arguments

Dataset catalog

The server bundles a curated catalog (see `src/catalog.ts`) covering these categories:

• Equity / OTC Market — weekly/monthly summaries, ATS and non-ATS block summaries, daily OTC list, consolidated short interest, Reg SHO daily volume, threshold list, ADF data.
• Fixed Income — TRACE corporate bonds, Treasury daily/monthly aggregates, agency & corporate debt breadth/sentiment indicators, 144A debt indicators, capped-volume datasets.
• Registration — firm profiles, registrations, disclosures, status history, broker-dealer lists, branch and individual records, registration validation, and more.
• Firm — Rule 4530 customer complaint filings.
• FINRA Content — the FINRA rulebook and industry-snapshot datasets.

The catalog is for discovery only — the API may accept additional `group`/`dataset` combinations not listed here. If `finra_describe_dataset` returns no entry, you can still try `finra_query` directly.

Prerequisites

• Node.js ≥ 20
• FINRA API credentials — a client ID and client secret provisioned from the FINRA API Console. You will need a FINRA account with access to the API Platform, and you must accept the data-set agreements for any non-public datasets you intend to query.

Installation

git clone 
cd finra-mcp-server
npm install
npm run build

This compiles TypeScript from `src/` into `dist/`. The entry point is `dist/index.js`.

npm scripts

Configuration

The server is configured entirely through environment variables.

If `FINRA_CLIENT_ID` or `FINRA_CLIENT_SECRET` is missing, the server exits at startup with an error directing you to provision credentials.

Usage

The server speaks MCP over stdio. It is launched by an MCP client, which communicates with it over standard input/output — you do not run it as a long-lived HTTP service.

Claude Desktop / Claude Code

Add the server to your MCP client configuration. For Claude Desktop, edit `claude_desktop_config.json`; for Claude Code, use `claude mcp add` or edit `.mcp.json`.

{
  "mcpServers": {
    "finra": {
      "command": "node",
      "args": ["/absolute/path/to/finra-mcp-server/dist/index.js"],
      "env": {
        "FINRA_CLIENT_ID": "your-client-id",
        "FINRA_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

For Claude Code, the equivalent CLI command is:

claude mcp add finra \
  --env FINRA_CLIENT_ID=your-client-id \
  --env FINRA_CLIENT_SECRET=your-client-secret \
  -- node /absolute/path/to/finra-mcp-server/dist/index.js

Restart the client after editing the configuration. The FINRA tools will then be available to the model.

Running directly

For local testing you can run the server directly. It will wait for an MCP client to connect over stdio:

export FINRA_CLIENT_ID=your-client-id
export FINRA_CLIENT_SECRET=your-client-secret
npm start

To exercise it interactively, use the MCP Inspector:

FINRA_CLIENT_ID=... FINRA_CLIENT_SECRET=... \
  npx @modelcontextprotocol/inspector node dist/index.js

Examples

These show the arguments a model would pass to each tool.

Discover datasets in a category:

// finra_list_datasets
{ "category": "Fixed Income" }

Recent TRACE trades for a bond by CUSIP:

// finra_trace_corporate_bonds
{ "cusip": "037833DX5", "startDate": "2026-01-01", "endDate": "2026-03-31", "limit": 200 }

Short interest for a symbol:

// finra_short_interest
{ "symbol": "AAPL", "startDate": "2026-01-01", "endDate": "2026-06-01" }

Look up a firm by CRD number:

// finra_firm_profile
{ "crdNumber": "7691" }

Arbitrary query with the generic tool:

// finra_query
{
  "group": "otcMarket",
  "dataset": "weeklySummary",
  "compareFilters": [
    { "fieldName": "issueSymbolIdentifier", "fieldValue": "TSLA", "compareType": "EQUAL" }
  ],
  "dateRangeFilters": [
    { "fieldName": "weekStartDate", "startDate": "2026-01-01", "endDate": "2026-06-01" }
  ],
  "sortFields": ["-weekStartDate"],
  "limit": 50
}

Each tool returns a JSON object containing the dataset identifiers, the total `recordCount` reported by the API, the number of records `returned`, and the `records` array.

How it works

• Authentication (`src/finra-client.ts`) — On the first request the client exchanges its base64-encoded `clientId:clientSecret` for a bearer token at `FINRA_TOKEN_URL`, then caches it. Tokens are reused until ~30 seconds before expiry (capped at 30 minutes) and refreshed automatically.
• Request shaping — Requests with filters, projections, or sorts are sent as `POST` with a JSON body; simple unfiltered requests use `GET` with query-string pagination. The total record count is read from the `record-count` response header.
• Tool layer (`src/tools.ts`) — Zod schemas validate every tool's arguments and are converted to JSON Schema for the MCP `tools/list` response. Curated tools translate friendly arguments into the underlying `compareFilters`/`dateRangeFilters` shape.

Project structure

src/
  index.ts         MCP server bootstrap (stdio transport, request handlers)
  config.ts        Environment-variable configuration loader
  finra-client.ts  OAuth2 token handling + Query API client
  tools.ts         Tool definitions, Zod schemas, and handlers
  catalog.ts       Local catalog of FINRA datasets

Notes & limitations

• Synchronous queries are capped at 5,000 records. For larger result sets, page with `limit`/`offset`. The Query API also supports an async mode for very large extracts; this server requests synchronous results.
• Data availability depends on your FINRA entitlements. Some datasets require accepting additional data agreements in the API Console.
• Field names (e.g. `issueSymbolIdentifier`, `tradeReportDate`, `firmCrdNumber`) follow FINRA's schema. Consult the FINRA developer catalog for the exact fields available in each dataset.

License

Released under the MIT License.