Skip to content
Back to search

Equibles

Self-hosted, open-source financial data MCP server for AI agents — SEC filings, XBRL financials, 13F holdings, insider & congressional trades, short interest, FRED, CFTC/CBOE and daily prices across 64 MCP tools. Equibles Cloud adds earnings call transcripts, live quotes, options chains with Greeks, guidance and a screener.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/daniel3303/Equibles with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/daniel3303/Equibles'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/daniel3303--equibles/badge.svg)](/listings/daniel3303--equibles)

HTML

<a href="/listings/daniel3303--equibles"><img src="/api/listings/daniel3303--equibles/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Docker Compose (recommended)

The fastest way to get everything running. Requires Docker.

git clone https://github.com/daniel3303/Equibles.git
cd Equibles
cp .env.example .env
# Edit .env and set SEC_CONTACT_EMAIL (required by SEC EDGAR fair access policy)
docker compose up

This starts:

| Service | Port | Description | |---------|------|-------------| | **db** | 5432 | ParadeDB (PostgreSQL + pgvector + pg_search) | | **web** | 8080 | Web portal for browsing data | | **mcp** | 8081 | MCP server for AI assistants | | **worker** | — | Scrapers (SEC, FINRA, Congress, FRED, Yahoo, CFTC, CBOE, USAspending, FDA, FIRDS, European exchange directories) |

Data scraping starts automatically. SEC filings, holdings, insider trades, and congressional trades will begin populating within minutes.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 507 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Equibles
  2. [![CI](https://github.com/daniel3303/Equibles/actions/workflows/ci.yml/badge.svg)](https://github.com/daniel3303/Equibles/actions/workflows/ci.yml)
  3. [![CodeQL](https://github.com/daniel3303/Equibles/actions/workflows/codeql.yml/badge.svg)](https://github.com/daniel3303/Equibles/actions/workflows/codeql.yml)
  4. [![codecov](https://codecov.io/github/daniel3303/Equibles/graph/badge.svg?token=ggkiHVv92U)](https://codecov.io/github/daniel3303/Equibles)
  5. [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
  6. [![.NET](https://img.shields.io/badge/.NET-10.0-512BD4?logo=dotnet&logoColor=white)](https://dotnet.microsoft.com/)
  7. [![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?logo=docker&logoColor=white)](docker-compose.yml)
  8. [![Self-Hosted](https://img.shields.io/badge/Self--Hosted-Ready-success?logo=serverless&logoColor=white)](docker-compose.yml)
  9. [![MCP](https://img.shields.io/badge/MCP-Compatible-8A2BE2?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0wIDE4Yy00LjQyIDAtOC0zLjU4LTgtOHMzLjU4LTggOC04IDggMy41OCA4IDgtMy41OCA4LTggOHoiLz48L3N2Zz4=)](https://modelcontextprotocol.io)
  10. **Equibles is a self-hosted, open-source financial data MCP server** — an open-source alternative to a Bloomberg Terminal, built for AI agents rather than humans. It scrapes, stores, and serves SEC filings and XBRL financials, 13F institutional holdings, insider and congressional trades, FINRA/SEC short data, FRED economic indicators, CFTC and CBOE positioning, fund filings, government contracts, and daily stock prices, and exposes them over the Model Context Protocol, so Claude, ChatGPT, Cursor, or any agent can query them directly. Its stock universe covers US listings plus verified listings on the major European exchanges. Runs on your own hardware with Docker, for free, forever.
  11. **This is the open-source core of [Equibles](https://equibles.com).** [Equibles Cloud](https://equibles.com/mcp) runs this exact core and adds more tools on top: earnings call transcripts and audio, real-time quotes, options chains with Greeks, LLM-extracted KPIs and guidance, buybacks, IPO filings, executive changes, valuation multiples, index composition, portfolio tracking, and a US-market screener. It also lists Chinese and Hong Kong shares beside the European ones. Same protocol, same tool names, nothing to run — see [what's included](#whats-included).
  12. > **Don't want to run anything?** Point your AI assistant at `https://mcp.equibles.com/mcp` and get a free API key at [equibles.com/mcp](https://equibles.com/mcp) — 100 requests/day, no card. Per-client setup guides live at [daniel3303/stock-market-mcp-server](https://github.com/daniel3303/stock-market-mcp-server).
  13. See [`docs/`](docs/README.md) for the user guide and technical documentation.
  14. ## What's Included
  15. Everything marked **Self-hosted** is scraped, stored, and served by this repo — **71 MCP tools**, no account, no key. [Equibles Cloud](https://equibles.com) runs this exact core over the same protocol with the same tool names, and adds more tools on top.
  16. | Domain | Data Source | Self-hosted | [Equibles Cloud](https://equibles.com) | Description |
  17. |--------|------------|:---:|:---:|-------------|
  18. | **SEC Filings** | SEC EDGAR | ✅ | ✅ | Annual, quarterly and current reports (10-K, 10-Q, 8-K, 20-F, 6-K, 40-F), proxies (DEF 14A, DEFA14A, PRE 14A), registration statements (S-1, S-3, S-3ASR, S-4, F-1, F-3, F-3ASR, F-4), tender offers (SC TO, SC 14D9) and late-filing notices (NT 10-K, NT 10-Q, NT 20-F), with full-text search |
  19. | **Financial Statements** | SEC XBRL | ✅ | ✅ | Parsed income statement, balance sheet, and cash flow facts per fiscal period |
  20. | **Holdings** | SEC 13F-HR | ✅ | ✅ | Institutional ownership — who owns what, how much, and trend over time |
  21. | **Fund Filings** | SEC NPORT / N-CEN / Form D | ✅ | ✅ | Fund portfolio holdings, registered-fund operations (service providers, fund types, advisers by CRD), and exempt offerings (private placements) |
  22. | **Investment Advisers** | SEC Form ADV | ✅ | ✅ | SEC-registered and exempt reporting advisers — assets under management, main office, employee count, fee structure |
  23. | **Insider Trading** | SEC Forms 3/4/5/144 | ✅ | ✅ | Director, officer, and 10% owner transactions, annual ownership statements, and proposed (Form 144) sales |
  24. | **Congressional Trading** | House/Senate disclosures | ✅ | ✅ | Securities transactions by members of Congress, including the filed stock, option, bond, or other instrument |
  25. | **Short Data** | SEC / FINRA | ✅ | ✅ | Fails-to-deliver (SEC), daily short volume and short interest (FINRA) |
  26. | **Economic Indicators** | FRED (Federal Reserve), Bank of Canada, Statistics Canada | ✅ | ✅ | US and Canadian interest rates, inflation, employment, GDP, yield spreads, and more |
  27. | **Stock Prices** | Yahoo Finance | ✅ | ✅ | Daily OHLCV prices with technical indicators (SMA, RSI, MACD) |
  28. | **European Listings** | ESMA/FCA FIRDS + exchange directories | ✅ | ✅ | Verified share listings on Euronext (Paris, Amsterdam, Brussels, Dublin, Oslo, Milan, Lisbon), Xetra, Nasdaq Stockholm, Helsinki and Copenhagen (main market and First North), BME, GPW and the London Stock Exchange (main market and AIM), keyed by ISIN and venue, with daily prices in the listing's own currency; every market with a directory adapter runs automatically; the price, dividend, financial-statement and fund-holding MCP tools accept them as `MIC:TICKER` (`XPAR:AIR`; see `docs/equity-identity.md`) |
  29. | **Futures Positioning** | CFTC | ✅ | ✅ | Commitments of Traders (COT) data for 30+ futures contracts |
  30. | **Market Indicators** | CBOE | ✅ | ✅ | VIX volatility index (1990+) and put/call ratios by category |
  31. | **Government Contracts** | USAspending.gov, open.canada.ca | ✅ | ✅ | US federal contract awards to public companies (amounts, awarding agencies, dates, NAICS/PSC codes) and Government of Canada contracts over C$10,000 to companies listed in Canada, reported since fiscal 2017-2018 |
  32. | **FDA Catalysts** | FDA.gov | ✅ | ✅ | Advisory-committee (AdComm) meeting calendar — scheduled FDA panel dates, center, and title that act as regulatory catalysts for biotech/pharma stocks |
  33. | **Earnings Call Transcripts** | Company webcasts | — | ✅ | Full quarterly-call transcripts with speaker attribution, searchable alongside filings |
  34. | **Earnings Call Audio** | Company webcasts | — | ✅ | The recorded call itself, playable and aligned to the transcript |
  35. | **Earnings Briefs, Guidance & Narrative Shift** | Earnings calls + releases | — | ✅ | Verifier-approved quarter summaries, call quotes, derived narrative changes, management guidance revisions, and reported results versus prior company guidance |
  36. | **Live Quotes** | Licensed market feed | — | ✅ | Real-time US equity quotes |
  37. | **Options Chains** | Licensed options feed | — | ✅ | Chains by expiration and strike with bid/ask, volume, open interest, implied volatility, and delta/gamma/theta/vega |
  38. | **Company KPIs** | Filings + earnings releases | — | ✅ | Operating metrics a company reports but XBRL never standardised, plus GAAP-to-non-GAAP bridges |
  39. | **Guidance** | Earnings releases + calls | — | ✅ | Management's forward guidance, its ranges, and how it moved between quarters |
  40. | **Buybacks & ATM** | 8-K / 10-Q | — | ✅ | Authorised repurchase programs and at-the-market equity programs, with amounts and dates |
  41. | **IPO Feed** | SEC S-1 / F-1 | — | ✅ | New registrations with offer terms, underwriters, risk factors, and pre-IPO financials |
  42. | **Investor Relations** | Company IR sites | — | ✅ | Upcoming events, conference appearances, and IR newsroom releases |
  43. | **Executives** | SEC 8-K / DEF 14A | — | ✅ | Appointments and departures, plus Summary Compensation Table figures |
  44. | **Valuation Multiples** | Derived | — | ✅ | Current and historical P/E, P/S, P/B, EV/EBIT, EV/EBITDA and more, with the periods each was computed from |
  45. | **Screener** | Derived | — | ✅ | Filter every US listing on valuation, margins, growth, ownership, short data, and dividends, and browse European, Chinese and Hong Kong listings by market |
  46. | **Smart Money** | Derived | — | ✅ | Insider sentiment scores, super-investor portfolios, and market-wide congressional activity |
  47. | **Risk Flags** | SEC filings | — | ✅ | Going-concern language and customer-concentration disclosures |
  48. | **Market Context** | Derived | — | ✅ | Correlated stocks, plus market calendar and open/closed status |
  49. | **Index Composition** | SEC N-PORT + fund holdings files | — | ✅ | Constituents and membership-change history for the S&P 500/400/600, Nasdaq-100, Russell 1000/2000, and the Dow, plus rule-based addition and deletion forecasts |
  50. | **Portfolios** | Your own account | — | ✅ | Track holdings and watchlists across stocks and options, with cost basis and realized/unrealized P&L. The only tools on the server that write |
  51. ## Why Some Data Is Cloud-Only
  52. Nothing above is held back from this repo. The cloud-only rows are data whose *production* needs infrastructure you would not stand up at home:
  53. - **Transcripts and audio** — earnings calls are webcasts, not filings. Each one has to be discovered and recorded by a browser fleet, then put through GPU speech-to-text with speaker diarization, every call, every quarter.
  54. - **Live quotes and options chains** — licensed real-time feeds, plus an always-on streaming service to fan them out. Neither the licence nor the uptime fits in a container on a laptop.
  55. - **KPIs, guidance, buybacks, IPO terms, executives, risk flags** — pulled out of filings, proxies, and earnings releases by LLM extraction lanes with verification passes and a human review queue, which needs sustained inference capacity.
  56. - **Investor-relations events and news** — collected from thousands of company IR sites, needing the same stealth browser fleet as the webcasts.
  57. - **Multiples, screener, smart money, market context** — derived, and only meaningful over a fully backfilled corpus of the whole market rather than the tickers you happen to have scraped so far.
  58. - **Index composition** — assembled from every tracking fund's N-PORT schedule plus each fund's own holdings file fetched daily, which needs the full NPORT corpus and a fetcher that keeps re-learning where those files moved to.
  59. - **Portfolios** — not scraped data at all: it is your own, stored against your account. The self-hosted build has no accounts, so there is nothing to store it against.
  60. Beyond the data, the cloud is already backfilled and kept current, and it is managed — no scrapers to babysit. This repo is free forever under AGPL-3.0; the cloud has a free tier at 100 requests/day with no card.
  61. Start on [the free tier](https://equibles.com/mcp), and self-host whenever you'd rather own the stack.
  62. ## Quick Start
  63. ### Docker Compose (recommended)
  64. The fastest way to get everything running. Requires Docker.
  65. ```bash
  66. git clone https://github.com/daniel3303/Equibles.git
  67. cd Equibles
  68. cp .env.example .env
  69. # Edit .env and set SEC_CONTACT_EMAIL (required by SEC EDGAR fair access policy)
  70. docker compose up
  71. ```
  72. This starts:
  73. | Service | Port | Description |
  74. |---------|------|-------------|
  75. | **db** | 5432 | ParadeDB (PostgreSQL + pgvector + pg_search) |
  76. | **web** | 8080 | Web portal for browsing data |
  77. | **mcp** | 8081 | MCP server for AI assistants |
  78. | **worker** | — | Scrapers (SEC, FINRA, Congress, FRED, Bank of Canada, Statistics Canada, Yahoo, CFTC, CBOE, USAspending, open.canada.ca contracts, FDA, FIRDS, European exchange directories) |
  79. Data scraping starts automatically. SEC filings, holdings, insider trades, and congressional trades will begin populating within minutes.
  80. ## Configuration
  81. All settings can be configured via a `.env` file in the project root (recommended for Docker) or environment variables.
  82. **FINRA Short Data (free API key required):**
  83. The FINRA scraper (short volume and short interest) requires a free API key. Without it, the scraper skips gracefully and all other scrapers run normally. Fails-to-deliver data comes from SEC and works without FINRA credentials.
  84. To get a key:
  85. 1. Go to the [FINRA API Console](https://gateway.finra.org/app/api-console) and sign in (a Google account works)
  86. 2. Open the **API Credentials** menu and create a new **API Key**
  87. 3. Copy the **Client ID** and **Client Secret**
  88. 4. Set `Finra__ClientId` and `Finra__ClientSecret` in your `.env` file or environment variables
  89. > The older `developer.finra.org` "Teams & Apps" flow has been retired — use the API Console above.
  90. **FRED Economic Data (free API key required):**
  91. The FRED scraper requires a free API key from the Federal Reserve Bank of St. Louis. Without it, the scraper skips gracefully and all other scrapers run normally.
  92. To get a key:
  93. 1. Register at [fred.stlouisfed.org/docs/api/api_key.html](https://fred.stlouisfed.org/docs/api/api_key.html)
  94. 2. Copy the 32-character API key
  95. 3. Set `Fred__ApiKey` in your `.env` file or environment variables
  96. **Ticker Filtering (optional):**
  97. By default, all tickers are synced. To limit data syncing to specific stocks, set a single ticker list that applies to all scrapers:
  98. ```env
  99. # .env — sync only these tickers (applies to all scrapers)
  100. Worker__TickersToSync__0=AAPL
  101. Worker__TickersToSync__1=MSFT
  102. Worker__TickersToSync__2=GOOGL
  103. ```
  104. When not set, all stocks are synced.
  105. **Minimum Sync Date (optional):**
  106. By default, all scrapers start from January 2020. Set a more recent date for faster initial sync, or go as far back as 2000-01-01 for more historical data:
  107. ```env
  108. # .env — start syncing from 2024 instead of 2020
  109. Worker__MinSyncDate=2024-01-01
  110. ```
  111. **Embedding (opt-in):**
  112. | Setting | Default | Description |
  113. |---------|---------|-------------|
  114. | `Embedding__Enabled` | `false` | Set to `true` to enable vector embedding generation |
  115. | `Embedding__Provider` | `Ollama` | `Ollama` (`/api/embed`) or `OpenAI` (`/v1/embeddings` — vLLM, Text-Embeddings-Inference, or OpenAI) |
  116. | `Embedding__BaseUrl` | — | Embedding endpoint (e.g., `http://localhost:11434`) |
  117. | `Embedding__ModelName` | — | Model name (e.g., `qwen3-embedding:0.6b`) |
  118. | `Embedding__ApiKey` | — | Bearer token, if the server requires one (e.g. vLLM `--api-key`) |
  119. | `Embedding__BatchSize` | `10` | Texts per embedding batch |
  120. **Update notifications (optional):**
  121. | Setting | Default | Description |
  122. |---------|---------|-------------|
  123. | `CHECK_FOR_UPDATES` | `true` | When `true`, the web portal checks GitHub Releases and shows a banner when a newer version is available. Set to `false` to disable. |
  124. **Authentication (optional):**
  125. | Setting | Default | Description |
  126. |---------|---------|-------------|
  127. | `AUTH_USERNAME` | — | Web portal username (auth disabled if empty) |
  128. | `AUTH_PASSWORD` | — | Web portal password (auth disabled if empty) |
  129. | `MCP_API_KEY` | — | MCP server API key (auth disabled if empty) |
  130. When set, the web portal requires login and the MCP server requires `Authorization: Bearer <key>` header. When unset, everything is open access (default).
  131. ## Updating
  132. The web portal checks GitHub Releases on a schedule and shows a banner when a newer version is available (disable with `CHECK_FOR_UPDATES=false`). To update to the latest release:
  133. **Docker Compose:**
  134. ```bash
  135. git pull
  136. docker compose up -d --build --remove-orphans
  137. ```
  138. Include any optional Compose override files in the upgrade command so those services remain enabled.
  139. **From source:**
  140. ```bash
  141. git pull
  142. dotnet build Equibles.sln
  143. ```
  144. Database migrations are applied automatically on startup. Review the [changelog](CHANGELOG.md) for notable changes before upgrading.
  145. ## Web Portal
  146. The web portal at `http://localhost:8080` provides a browser-based interface for exploring data:
  147. - **Stocks** — Browse and search all tracked companies, view price charts with technical indicators (SMA, EMA, RSI, MACD, Bollinger Bands), golden/death-cross and price-streak badges, performance versus SPY, plus per-stock tabs for institutional holdings, short data, SEC filings, financial statements, insider trading, proposed (Form 144) sales, fund holdings (NPORT), fund operations (N-CEN), exempt offerings (Form D), and congressional trades
  148. - **Institutions** — Browse institutional holders (hedge funds, asset managers), view detailed profiles with portfolio breakdowns, industry allocation, quarterly activity, backtesting, and side-by-side comparisons. Filers are scored on risk-adjusted performance (alpha vs. a benchmark) and a Smart Money Index page aggregates the highest-scoring funds into a consensus signal. Includes a holdings screener with filters (filer count, value, float %, location, AUM/position-count, industry) and CSV export
  149. - **Advisers** — Browse SEC-registered and exempt reporting investment advisers (`/advisers`), ranked by assets under management, with per-firm profiles (regulatory AUM, main office, employee count, fee structure)
  150. - **Insider Trading** — Dashboard showing the top insider buys, sells, and biggest transactions over the last 90 days
  151. - **Short Activity** — Most-shorted leaderboard (`/most-shorted`, ranked by FINRA short interest) and largest daily short volume (`/short-volume`), each with a date selector, server-side sort, and pagination
  152. - **Economy** — Browse US and Canadian economic indicators from FRED, the Bank of Canada and Statistics Canada, grouped by category (interest rates, inflation, employment, GDP, etc.) with charts and statistics
  153. - **Futures** — CFTC Commitments of Traders positioning data for 30+ futures contracts (commodities, indices, currencies) with commercial/non-commercial position charts
  154. - **Market** — CBOE market indicators: VIX volatility index with OHLC charts, put/call ratios (equity, index, total, VIX, ETP)
  155. - **Search** — Global search across stocks, institutions, insiders, and congress members with category filtering and date ranges
  156. - **Status** — System health, worker status, data counts, and error log
  157. ## MCP Server
  158. The MCP server exposes financial data tools for AI assistants (Claude, ChatGPT, etc.):
  159. - **Institutional Holdings** — Top holders, ownership history, institution portfolios and summary, sector allocation, quarterly activity, most-held stocks, consensus holdings, fund overlap, market-wide 13F activity, holder flows by kind of filer and sector, institution search
  160. - **Insider Trading** — Insider transactions, ownership summary, proposed (Form 144) sales, insider search
  161. - **Congressional Trading** — Trades for a ticker, trades by one member, member search
  162. - **SEC Documents** — Full-text search, semantic search, document browsing, keyword search within filings
  163. - **Financial Statements** — XBRL fact time series per ticker, cross-ticker fact comparison, full income statement / balance sheet / cash flow per fiscal period
  164. - **Fund & Adviser Filings** — Fund portfolio holdings (NPORT), registered-fund operations (N-CEN), exempt offerings (Form D), and SEC-registered and exempt reporting investment-adviser lookup and search (Form ADV)
  165. - **Short Data** — Daily short volume, market-wide largest daily short volume, bi-monthly short interest, and the latest short-interest snapshot across tickers
  166. - **Economic Indicators** — FRED, Bank of Canada and Statistics Canada lookup, a latest macro snapshot per country (US or CA), indicator search across categories
  167. - **Stock Prices** — Daily OHLCV history with adjusted close, latest close across one or more tickers, and on-demand technical indicators (EMA, Stochastic Oscillator, Average True Range, On-Balance Volume, Bollinger Bands)
  168. - **Futures Positioning** — COT positioning data, latest snapshot across all contracts, contract search
  169. - **Market Indicators** — VIX historical data, put/call ratios by type (equity, index, total, VIX, ETP)
  170. - **Government Contracts** — Federal contract awards won by a ticker (awarding agency, amount, period dates) and a ranking of the top public-company contractors by total federal dollars over a date range, for the US (USAspending.gov) or Canada (open.canada.ca proactive publication of contracts since fiscal 2017-2018, in Canadian dollars)
  171. - **FDA Catalysts** — Scheduled FDA advisory-committee (AdComm) meetings over a date range — the regulatory catalyst dates that move biotech and pharma stocks (FDA.gov)
  172. ### Output Format (GCF, opt-in)
  173. By default the table tools return markdown tables. [Graph Compact Format](https://gcformat.com)
  174. is used instead when it is smaller, otherwise it falls back to markdown. GCF carries the same
  175. cells the markdown table would show, with the column names factored into a single header and
  176. the per-cell `| ` padding and separator row dropped.
  177. It reaches the answers rendered through `MarkdownTable.Render`, which today is the short-volume
  178. and short-interest tools, off-exchange volume, fails-to-deliver, congressional trades and member
  179. disclosures, the FRED series and calendar tools, CFTC positioning, CBOE ratios, FDA advisory
  180. meetings, government contracts, and the institution and adviser search tools. Tools that assemble
  181. their answer with `MarkdownTable.Start` and append rows themselves are **not** encoded, because
  182. those answers continue past the table with truncation notes and footnotes; that includes the
  183. price, financial-statement, insider, dividend, 13F-portfolio, fund-filing and filing-search
  184. tools. Routing them through the shared renderer is tracked separately.
  185. Ask for it **per request**, which is what a shared server wants, with either the
  186. `X-Equibles-Output-Format: gcf` header or an `?output_format=gcf` query parameter (the query
  187. parameter is there for clients whose only configuration is a URL). `markdown` is accepted the
  188. same way, so a caller can opt out of a server that defaults to GCF. An unrecognized value is
  189. ignored rather than refused, and the server's own default applies.
  190. Set `EQUIBLES_OUTPUT_FORMAT=gcf` to make GCF the **process-wide** default instead. A request
  191. that names a format wins over it; one that names nothing gets it.
  192. Per-request selection relies on each tool call arriving as its own HTTP request, which is how
  193. the streamable HTTP transport works in both its stateless and session modes: the format is read
  194. off that request and applies to it alone. A transport that instead dispatched calls on a
  195. connection opened earlier would carry whatever the opening request asked for.
  196. How much it saves depends on the shape of the answer. The table compresses, the prose around
  197. it does not, so a small table inside a long preamble saves least and a wide table of many
  198. short values saves most. Measured end to end against a deployed server on real answers from
  199. three of the covered tools, 30 sessions of daily short volume, 25 congressional trades and 24
  200. monthly observations of a FRED series, the answer text is **7 to 13% shorter** in characters.
  201. That is the text your client hands the model, not the HTTP payload. JSON escapes every
  202. quotation mark the encoder adds, so the transport bytes can grow on the same answer whose text
  203. shrank.
  204. It is deliberately conservative: **every cell value is preserved verbatim** (the compact-USD,
  205. comma-grouped, adaptive-decimal and em-dash formatting is untouched — GCF only changes the
  206. framing, not the numbers a model reads), and any row that does not match the header's column
  207. shape falls back to the markdown table, so a result is never dropped or garbled. Output is
  208. unchanged for a caller that asks for nothing on a server that sets nothing. GCF is
  209. MIT-licensed and its encoder is
  210. zero-dependency.
  211. ### Connecting to Claude Desktop
  212. Add this to your Claude Desktop config file (`claude_desktop_config.json`):
  213. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  214. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  215. ```json
  216. {
  217. "mcpServers": {
  218. "equibles": {
  219. "url": "http://localhost:8081/mcp"
  220. }
  221. }
  222. }
  223. ```
  224. Restart Claude Desktop and the Equibles tools will be available. You can then ask questions like "Who are the top institutional holders of AAPL?" or "Search Apple's latest 10-K for revenue growth discussion."
  225. ### Connecting to Claude Code
  226. Add the MCP server to Claude Code:
  227. ```bash
  228. claude mcp add equibles --transport http http://localhost:8081/mcp
  229. ```
  230. ### Connecting to ChatGPT Desktop
  231. Add this to your ChatGPT Desktop config file:
  232. **macOS**: `~/Library/Application Support/com.openai.chat/mcp.json`
  233. **Windows**: `%APPDATA%\com.openai.chat\mcp.json`
  234. ```json
  235. {
  236. "servers": {
  237. "equibles": {
  238. "url": "http://localhost:8081/mcp"
  239. }
  240. }
  241. }
  242. ```
  243. Restart ChatGPT Desktop and the Equibles tools will be available.
  244. ### Connecting to OpenClaw
  245. In OpenClaw, add an MCP server with the URL `http://localhost:8081/mcp` (HTTP transport).
  246. ### Other MCP Clients
  247. Any MCP-compatible client can connect to `http://localhost:8081/mcp` (HTTP transport).
  248. ### Running over stdio
  249. Clients that launch a server as a subprocess can run it over stdin/stdout instead of HTTP:
  250. ```bash
  251. dotnet build src/Equibles.Mcp.Server
  252. dotnet run --no-build --project src/Equibles.Mcp.Server -- --stdio
  253. ```
  254. Build first: a plain `dotnet run` restores and prints build output on stdout, which corrupts the protocol stream. The server reads `ConnectionStrings:DefaultConnection` as usual, so point it at the same database the worker fills. Logs go to stderr. The API key and the per-request output-format header and query parameter do not apply; set `EQUIBLES_OUTPUT_FORMAT=gcf` in the subprocess environment instead.
  255. ## Tools
  256. This self-hosted build exposes 71 tools over MCP. The hosted server at `https://mcp.equibles.com/mcp` runs this same core and [adds more on top](#whats-included). Full catalog and client setup: [daniel3303/stock-market-mcp-server](https://github.com/daniel3303/stock-market-mcp-server).
  257. **13F institutional holdings**
  258. - GetInstitutionCloneBacktest — backtest cloning a filer's 13F portfolio vs a benchmark
  259. - GetTopHolders — top institutional holders of a stock (13F-HR), with each holder's type and measured style, filterable by both
  260. - GetInstitutionalOwnershipHistory — institutional ownership trend across quarters
  261. - GetAllHolders — every disclosed holder of a stock in one list (13F, 13D/13G, insiders, funds), one row per holder with its other filings and contained disclosures nested, or grouped by ultimate parent
  262. - GetOwnershipSummary — who owns a stock: institutions, insiders, 13D/G-only blocks and the remaining float as % of shares outstanding, with funds shown but never summed
  263. - GetBeneficialOwnership — a stock's Schedule 13D and 13G filers, each latest filing with every reporting person
  264. - GetHolderMix — who holds a stock by holder type, measured style, turnover, horizon, book size, client base, private funds or location, with each bucket's like-for-like change; or registered funds by N-CEN fund type (index funds, index ETFs, active ETFs, active funds) as a share of shares outstanding
  265. - GetOwnershipSignals — who holds a stock and how across every 13F book: conviction, crowding, ownership of the estimated free float, holder concentration, holding periods, the holders' estimated cost and share held at a loss, and holder-overlap peers
  266. - GetHolderTargets — shareholder targeting: 13F filers that hold a stock's holder-overlap peers but not the stock, ranked by money in the peers, with style and holder type
  267. - GetHolderTypeFlows — market-wide money in and out of US equities by kind of 13F filer for a closed quarter, optionally split by sector, with net flow as a share of each bucket's prior book
  268. - GetLatest13FFilings — the newest 13F filings loaded, with each one's SEC filing date and load time, and how many filings are loaded per recent filing day
  269. - GetInstitutionPortfolio — an institution's 13F portfolio, with how long each position has been held and its estimated cost per share
  270. - SearchInstitutions — strict-first tokenized name/CIK search with filing date, 13F AUM, position count, and holder type
  271. - GetTopInstitutionalBuyersSellers — biggest adds/reductions on a stock this quarter
  272. - GetMarketWide13FActivity — market-wide 13F leaderboards
  273. - GetMostHeldStocks — stocks by institutional breadth, conviction or crowding
  274. - GetInstitutionSummary — filer summary (value, concentration, turnover, holder profile, style bands)
  275. - GetInstitutionStyleHistory — a filer's measured style, turnover and horizon bands quarter by quarter
  276. - GetInstitutionSectorAllocation — allocation by sector
  277. - GetInstitutionQuarterlyActivity — initiated/increased/reduced/exited vs prior quarter
  278. - GetInstitutionBeneficialOwnership — an institution's Schedule 13D and 13G stakes, each with its dates and a status (current, unconfirmed, below 5%, exited, security retired)
  279. - CompareInstitutionPortfolios — portfolio overlap between two institutions
  280. - GetInstitutionConsensusHoldings — consensus portfolio of 2–25 institutions
  281. **Insider trading**
  282. - GetInsiderTransactions — insider transactions from Forms 4/5
  283. - GetInsiderOwnership — insider ownership ranked by shares
  284. - GetForm144ProposedSales — proposed sales from Form 144
  285. - SearchInsiders — strict-first whole-word filed-name search with verified public-name aliases
  286. **SEC filings search**
  287. - SearchDocuments — hybrid keyword+semantic search across all filings, optionally scoped by ticker
  288. - SearchDocument — search within a single filing
  289. - ListFilings — browse filings market-wide or for one company, with date/type/8-K item filters
  290. - ReadDocumentLines — read a line range from a filing
  291. **Funds, ETFs & advisers**
  292. - SearchInvestmentAdvisers — strict-first tokenized adviser-name search (Form ADV)
  293. - GetInvestmentAdviser — ADV profile by CRD
  294. - GetFundNcenReports — fund ops from N-CEN with exact directory-identifier resolution
  295. - GetFundsHoldingStock — funds holding a stock
  296. - GetFormDOfferings — private placements (Form D)
  297. - GetFailsToDeliver — SEC FTD data
  298. - SearchFunds — strict-first tokenized fund/registrant/ticker search with verified share-class aliases
  299. - GetFundProfile — fund profile + NPORT-P holdings with explicit reported-versus-stored coverage counts
  300. **Fundamentals (XBRL)**
  301. - GetFinancialStatement — income/balance/cash-flow statement anchored to one period end; quarterly currency flows are reported discrete quarters or exact derived remainders, never YTD totals
  302. - GetFinancialFact — one concept over time with exact spans and stale-alias coverage warnings
  303. - CompareFinancialFact — a concept across companies
  304. - GetRevenueBreakdown — revenue by segment/geography/product plus reported segment operating income and derived margin
  305. **Economic data (FRED, Bank of Canada, Statistics Canada)**
  306. - GetEconomicIndicator — a curated US or Canadian series
  307. - GetLatestEconomicIndicators — latest values by category for one country (US or CA)
  308. - SearchEconomicIndicators — strict-first tokenized curated-series search with standard macro aliases
  309. - GetEconomicCalendar — US and Canadian macro release calendar
  310. **Futures (CFTC COT)**
  311. - GetCftcPositioning — COT positioning for a contract
  312. - GetLatestCftcPositioning — latest COT snapshot
  313. - SearchCftcMarkets — strict-first tokenized search by name, code, or standard futures symbol
  314. **Volatility (CBOE)**
  315. - GetPutCallRatios — put/call ratios
  316. - GetVixHistory — VIX daily OHLC
  317. **FDA calendar**
  318. - GetFdaAdvisoryCommitteeMeetings — scheduled FDA advisory-committee meetings
  319. **Congressional trading**
  320. - GetCongressionalTrades — trades for a ticker
  321. - GetMemberTrades — a member's trades
  322. - GetMemberNetWorth — member net worth history
  323. - SearchCongressMembers — strict-first tokenized roster search with verified public-name aliases
  324. **Short data (FINRA)**
  325. - GetShortVolume — daily short volume
  326. - GetShortInterest — bi-monthly short interest
  327. - GetShortInterestSnapshot — market-wide snapshot
  328. - GetLargestShortVolume — largest daily short volume
  329. - GetShortSqueezeScores — composite squeeze scores
  330. - GetOffExchangeVolume — dark-pool/OTC volume
  331. **Stock prices**
  332. - GetStockPrices — daily OHLCV plus the stored auxiliary adjusted close when it differs
  333. - GetLatestClosingPrices — latest close/change/volume
  334. - GetDividendHistory — stored cash dividends for an exact stock or ETF listing
  335. - GetStochasticOscillator — stochastic oscillator (%K/%D)
  336. - GetAverageTrueRange — average true range (ATR)
  337. - GetOnBalanceVolume — on-balance volume (OBV)
  338. - GetBollingerBands — Bollinger Bands
  339. **Government contracts (USAspending, open.canada.ca)**
  340. - GetGovernmentContracts — federal contract awards for a company
  341. - GetTopGovernmentContractors — largest public-company contractors
  342. ## Vector Embeddings (advanced, opt-in)
  343. Vector embeddings enable semantic search over SEC filings (e.g., "find revenue growth discussion in Apple's 10-K"). This requires downloading the Ollama runtime (~2GB) and the Qwen3-Embedding-0.6B model (~640MB).
  344. ```bash
  345. docker compose -f docker-compose.yml -f docker-compose.embedding.yml up
  346. ```
  347. This adds Ollama and configures the existing web, MCP, and worker services to use it:
  348. | Service | Port | Description |
  349. |---------|------|-------------|
  350. | **embedding** | 11434 | Ollama server with Qwen3-Embedding-0.6B model |
  351. | **embedding-pull** | — | One-shot model download before the worker starts |
  352. | **worker** | — | The existing worker, with embedding generation enabled |
  353. Without the embedding override, BM25 full-text search via ParadeDB still works out of the box — vector search is purely additive.
  354. **Bundled Ollama is the default** because it needs no GPU and runs anywhere. For bulk embedding at scale, point `Embedding__Provider=OpenAI` at a batched server such as [vLLM](https://docs.vllm.ai) or [Text-Embeddings-Inference](https://github.com/huggingface/text-embeddings-inference) — they continuously batch on the GPU and are far faster than Ollama for large corpora. See [docs/guide/how-to-use-external-embedding-endpoint.md](docs/guide/how-to-use-external-embedding-endpoint.md).
  355. ## Screenshots
  356. <table>
  357. <tr>
  358. <td width="50%"><strong>Stock Detail</strong><br><img alt="Stock detail page showing price charts, moving averages, and technical indicators for AAPL" src="docs/screenshots/stock-detail.png"></td>
  359. <td width="50%"><strong>Stocks</strong><br><img alt="Stocks page with search and ticker listing" src="docs/screenshots/stocks-list.png"></td>
  360. </tr>
  361. <tr>
  362. <td width="50%"><strong>Economic Data</strong><br><img alt="Economic indicators grouped by category" src="docs/screenshots/economy.png"></td>
  363. <td width="50%"><strong>Economic Indicator Detail</strong><br><img alt="Federal Funds Rate chart and observations" src="docs/screenshots/economy-detail.png"></td>
  364. </tr>
  365. </table>
  366. ## Contributing
  367. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project architecture, and how to extend the platform. Contributors must sign the [Contributor License Agreement](CLA.md) — this is handled automatically by a bot when you open a pull request.
  368. ## License
  369. [AGPL-3.0](LICENSE)
  370. ## Author
  371. Daniel Oliveira
  372. [![Website](https://img.shields.io/badge/Website-FF6B6B?style=for-the-badge&logo=safari&logoColor=white)](https://danielapoliveira.com/)
  373. [![X](https://img.shields.io/badge/X-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/daniel_not_nerd)
  374. [![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/daniel-ap-oliveira/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.