finra-mcp-server
About
A Model Context Protocol (MCP) server that exposes the FINRA Query API as a set of tools.
Details
- Author
- cmaurer
- Categories
- Finance, API, Other
Jump to
Setup
Install finra-mcp-server in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/cmaurer/finra-mcp-server
Follow the installation instructions in the repository README, then restart your MCP client.
AModel Context Protocol(MCP) server that exposes theFINRA Query APIas 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.
FINRA publishes a large family of datasets through a single Query API surface:
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 catalogso the model can discover validgroup/datasetcombinations without guessing.
- Curated convenience toolsfor 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.
The server bundles a curated catalog (seesrc/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 additionalgroup/datasetcombinations not listed here. Iffinra_describe_datasetreturns no entry, you can still tryfinra_querydirectly.
- Node.js ≥ 20
- FINRA API credentials— a client ID and client secret provisioned from theFINRA 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.
git clone <this-repo-url> cd finra-mcp-server npm install npm run build
This compiles TypeScript fromsrc/intodist/. The entry point isdist/index.js.
The server is configured entirely through environment variables.
IfFINRA_CLIENT_IDorFINRA_CLIENT_SECRETis missing, the server exits at startup with an error directing you to provision credentials.
The server speaks MCP overstdio. 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.
Add the server to your MCP client configuration. For Claude Desktop, editclaude_desktop_config.json; for Claude Code, useclaude mcp addor 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.
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 theMCP Inspector:
FINRA_CLIENT_ID=... FINRA_CLIENT_SECRET=... \ npx @modelcontextprotocol/inspector node dist/index.js
These show the arguments a model would pass to each tool.
// 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 }
// finra_short_interest { "symbol": "AAPL", "startDate": "2026-01-01", "endDate": "2026-06-01" }
// finra_firm_profile { "crdNumber": "7691" }
// 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 totalrecordCountreported by the API, the number of recordsreturned, and therecordsarray.
- Authentication(src/finra-client.ts) — On the first request the client exchanges its base64-encodedclientId:clientSecretfor a bearer token atFINRA_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 asPOSTwith a JSON body; simple unfiltered requests useGETwith query-string pagination. The total record count is read from therecord-countresponse header.
- Tool layer(src/tools.ts) — Zod schemas validate every tool's arguments and are converted to JSON Schema for the MCPtools/listresponse. Curated tools translate friendly arguments into the underlyingcompareFilters/dateRangeFiltersshape.
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
- Synchronous queries are capped at 5,000 records.For larger result sets, page withlimit/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 theFINRA developer catalogfor the exact fields available in each dataset.
Brazilian Open Finance MCP — connect 30+ banks (Itaú, Nubank, Bradesco, Santander, Inter, BB, Caixa, C6 and more) to Claude/Cursor. 13 read-only tools.
Live MCP server connecting AI agents to 36+ business data sources. OAuth 2.1 PKCE.
US stock market & financial data — SEC filings full-text search, XBRL fundamentals, 13F institutional holdings, insider & congressional trades, earnings-call transcripts, short interest, and FRED macro; 90+ tools, free tier, self-hostable.
Get financial data and details about Romanian companies straight from ONRC and ANAF
Access BIST and global market data directly
Macroeconomic and FX data API + MCP server for 18 currencies with central bank announcements, calendar, COT, commodities, and forex.
MCP (Model Context Protocol) server for Kontomierz.pl — a Polish personal finance platform. Enables AI assistants (Claude Desktop, LibreChat, Cline) to read and manage your bank accounts, transactions, budgets, and scheduled payments — all through a single API. Built in Python, runs locally or in Docker.
Company, KYB, VAT, sanctions, LEI and address data for 15 EU countries (DK, NO, SE, FI, IE, UK, FR, DE, CZ, PL, LV, EE, NL, BE, LU). Free tier 100 lookups/day at addonnordic.com.
Cert-free PSD2 bank data API for AI agents — read EU bank transactions and balances without buying an eIDAS QWAC certificate
A production-clean MCP server for exchange rates (ECB data via Frankfurter) — latest, convert, historical, and time-series, with SRE-grade rate limiting, backoff, and structured logging.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
