Labsco
cmaurer logo

finra-mcp-server

★ 1

from cmaurer

A Model Context Protocol (MCP) server that exposes the FINRA Query API as a set of tools.

🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#automation#git#finance#translation

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:

Copy & paste — that's it
/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

ToolDescription
finra_queryGeneric Query API request. Supports compareFilters, dateRangeFilters, domainFilters, field projection, sorting, and pagination. Sync cap is 5,000 records.
finra_list_datasetsList datasets in the local catalog, optionally filtered by category or a search substring. Use this first to discover valid group/dataset names.
finra_describe_datasetLook up catalog metadata for a specific group/dataset.
finra_trace_corporate_bondsCurated wrapper for TRACE corporate-bond trade reports (fixedIncomeMarket/trace). Filter by cusip, symbol, or trade-date range.
finra_short_interestCurated wrapper for consolidated short interest (otcMarket/consolidatedShortInterest). Filter by symbol and/or settlement-date range.
finra_otc_weekly_summaryCurated wrapper for OTC equity weekly trade summary (otcMarket/weeklySummary). Filter by symbol and/or week-ending date.
finra_firm_profileCurated wrapper for firm profile lookup (registration/firmProfile). Provide a CRD number.

finra_query arguments

ArgumentTypeDescription
groupstring (required)Dataset group, e.g. otcMarket, fixedIncomeMarket, registration.
datasetstring (required)Dataset name within the group, e.g. weeklySummary, trace.
fieldsstring[]Subset of fields to return. Omit for all fields.
compareFiltersobject[]Field comparisons: { fieldName, fieldValue, compareType } where compareType is one of EQUAL, NOT_EQUAL, GREATER, LESSER, GREATER_EQUAL, LESSER_EQUAL, LIKE.
dateRangeFiltersobject[]{ fieldName, startDate, endDate } with ISO yyyy-MM-dd dates.
domainFiltersobject[]IN-list filters: { fieldName, values: [...] }.
sortFieldsstring[]Sort fields; prefix with - for descending.
limitnumberMax records (1–5,000 for synchronous requests). Defaults to 100.
offsetnumberPagination offset (0–500,000). Defaults to 0.

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.

Examples

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

Discover datasets in a category:

Copy & paste — that's it
// finra_list_datasets
{ "category": "Fixed Income" }

Recent TRACE trades for a bond by CUSIP:

Copy & paste — that's it
// finra_trace_corporate_bonds
{ "cusip": "037833DX5", "startDate": "2026-01-01", "endDate": "2026-03-31", "limit": 200 }

Short interest for a symbol:

Copy & paste — that's it
// finra_short_interest
{ "symbol": "AAPL", "startDate": "2026-01-01", "endDate": "2026-06-01" }

Look up a firm by CRD number:

Copy & paste — that's it
// finra_firm_profile
{ "crdNumber": "7691" }

Arbitrary query with the generic tool:

Copy & paste — that's it
// 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

Copy & paste — that's it
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

License

Released under the MIT License.