Equibles

An open-source, self-hosted mini Bloomberg Terminal for AI agents. Scrapes, stores, and serves SEC filings, institutional holdings, insider trading, congressional trades, short data, economic indicators, and daily stock prices — and exposes it all via MCP so your AI assistant can query it directly.

Powers equibles.com.

See docs/ for the user guide and technical documentation.

Prefer not to self-host? The MCP server also runs as a managed service at https://mcp.equibles.com/mcp with a free tier (100 requests/day). Per-client setup guides live at daniel3303/stock-market-mcp-server.

What's Included

Quick Start

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:

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

Configuration

All settings can be configured via a .env file in the project root (recommended for Docker) or environment variables.

FINRA Short Data (free API key required):

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.

To get a key:

1. Go to the FINRA API Console and sign in (a Google account works)
2. Open the API Credentials menu and create a new API Key
3. Copy the Client ID and Client Secret
4. Set Finra__ClientId and Finra__ClientSecret in your .env file or environment variables

The older developer.finra.org "Teams & Apps" flow has been retired — use the API Console above.

FRED Economic Data (free API key required):

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.

To get a key:

1. Register at fred.stlouisfed.org/docs/api/api_key.html
2. Copy the 32-character API key
3. Set Fred__ApiKey in your .env file or environment variables

Ticker Filtering (optional):

By default, all tickers are synced. To limit data syncing to specific stocks, set a single ticker list that applies to all scrapers:

# .env — sync only these tickers (applies to all scrapers)
Worker__TickersToSync__0=AAPL
Worker__TickersToSync__1=MSFT
Worker__TickersToSync__2=GOOGL

When not set, all stocks are synced.

Minimum Sync Date (optional):

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:

# .env — start syncing from 2024 instead of 2020
Worker__MinSyncDate=2024-01-01

Embedding (opt-in):

Update notifications (optional):

Authentication (optional):

When set, the web portal requires login and the MCP server requires Authorization: Bearer <key> header. When unset, everything is open access (default).

Updating

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:

Docker Compose:

git pull
docker compose up -d --build

From source:

git pull
dotnet build Equibles.sln

Database migrations are applied automatically on startup. Review the changelog for notable changes before upgrading.

Web Portal

The web portal at http://localhost:8080 provides a browser-based interface for exploring data:

• 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
• 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
• Advisers — Browse SEC-registered investment advisers (/advisers), ranked by assets under management, with per-firm profiles (regulatory AUM, main office, employee count, fee structure)
• Insider Trading — Dashboard showing the top insider buys, sells, and biggest transactions over the last 90 days
• 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
• Economy — Browse FRED economic indicators grouped by category (interest rates, inflation, employment, GDP, etc.) with charts and statistics
• Futures — CFTC Commitments of Traders positioning data for 30+ futures contracts (commodities, indices, currencies) with commercial/non-commercial position charts
• Market — CBOE market indicators: VIX volatility index with OHLC charts, put/call ratios (equity, index, total, VIX, ETP)
• Search — Global search across stocks, institutions, insiders, and congress members with category filtering and date ranges
• Status — System health, worker status, data counts, and error log

MCP Server

The MCP server exposes financial data tools for AI assistants (Claude, ChatGPT, etc.):

• 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, institution search
• Insider Trading — Insider transactions, ownership summary, proposed (Form 144) sales, insider search
• Congressional Trading — Trades for a ticker, trades by one member, member search
• SEC Documents — Full-text search, semantic search, document browsing, keyword search within filings
• Financial Statements — XBRL fact time series per ticker, cross-ticker fact comparison, full income statement / balance sheet / cash flow per fiscal period
• Fund & Adviser Filings — Fund portfolio holdings (NPORT), registered-fund operations (N-CEN), exempt offerings (Form D), and SEC-registered investment-adviser lookup and search (Form ADV)
• Short Data — Daily short volume, market-wide largest daily short volume, bi-monthly short interest, and the latest short-interest snapshot across tickers
• Economic Indicators — FRED data lookup, latest macro snapshot, indicator search across categories
• 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)
• Futures Positioning — COT positioning data, latest snapshot across all contracts, contract search
• Market Indicators — VIX historical data, put/call ratios by type (equity, index, total, VIX, ETP)
• 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 (USAspending.gov)
• FDA Catalysts — Scheduled FDA advisory-committee (AdComm) meetings over a date range — the regulatory catalyst dates that move biotech and pharma stocks (FDA.gov)

Connecting to Claude Desktop

Add this to your Claude Desktop config file (claude_desktop_config.json):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "equibles": {
      "url": "http://localhost:8081/mcp"
    }
  }
}

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

Connecting to Claude Code

Add the MCP server to Claude Code:

claude mcp add equibles --transport http http://localhost:8081/mcp

Connecting to ChatGPT Desktop

Add this to your ChatGPT Desktop config file:

macOS: ~/Library/Application Support/com.openai.chat/mcp.json Windows: %APPDATA%\com.openai.chat\mcp.json

{
  "servers": {
    "equibles": {
      "url": "http://localhost:8081/mcp"
    }
  }
}

Restart ChatGPT Desktop and the Equibles tools will be available.

Connecting to OpenClaw

In OpenClaw, add an MCP server with the URL http://localhost:8081/mcp (HTTP transport).

Other MCP Clients

Any MCP-compatible client can connect to http://localhost:8081/mcp (HTTP transport).

Tools

This self-hosted build exposes 62 tools over MCP; the hosted server at https://mcp.equibles.com/mcp adds 28 more commercial tools — see daniel3303/stock-market-mcp-server for the full catalog and client setup.

13F institutional holdings

• GetFundCloneBacktest — backtest cloning a filer's 13F portfolio vs a benchmark
• GetTopHolders — top institutional holders of a stock (13F-HR)
• GetOwnershipHistory — institutional ownership trend across quarters
• GetInstitutionPortfolio — an institution's 13F portfolio
• SearchInstitutions — search institutions by name or CIK
• GetTopBuyersSellers — biggest adds/reductions on a stock this quarter
• GetMarketWide13FActivity — market-wide 13F leaderboards
• GetMostHeldStocks — stocks by institutional breadth
• GetInstitutionSummary — filer summary (value, concentration, turnover)
• GetInstitutionSectorAllocation — allocation by sector
• GetInstitutionQuarterlyActivity — initiated/increased/reduced/exited vs prior quarter
• GetFundOverlap — portfolio overlap between two institutions
• GetConsensusHoldings — consensus portfolio of 2–25 institutions

Insider trading

• GetInsiderTransactions — insider transactions from Form 3/4/5
• GetInsiderOwnership — insider ownership ranked by shares
• GetProposedSales — proposed sales from Form 144
• SearchInsiders — search insiders by name

SEC filings search

• SearchDocuments — hybrid keyword+semantic search across all filings
• SearchCompanyDocuments — one company's filings by ticker
• SearchDocument — search within a single filing
• ListCompanyDocuments — browse a company's filings
• SearchDocumentKeyword — keyword search in one filing
• ReadDocumentLines — read a line range from a filing

Funds, ETFs & advisers

• SearchInvestmentAdvisers — search advisers (Form ADV)
• GetInvestmentAdviser — ADV profile by CRD
• GetFundOperations — fund ops from N-CEN
• GetFundHoldings — fund holdings from NPORT-P
• GetFundsHoldingStock — funds holding a stock
• GetExemptOfferings — private placements (Form D)
• GetFailsToDeliver — SEC FTD data
• SearchFunds — search registered funds/ETFs
• GetFundProfile — fund profile + largest holdings

Fundamentals (XBRL)

• GetFinancialStatement — income/balance/cash-flow statement by period
• GetFinancialFact — one concept over time
• CompareFinancialFact — a concept across companies
• GetRevenueBreakdown — revenue by segment/geography/product

Economic data (FRED)

• GetEconomicIndicator — a FRED series
• GetLatestEconomicData — latest values by category
• SearchEconomicIndicators — search curated series
• GetEconomicCalendar — US macro release calendar

Futures (CFTC COT)

• GetCftcPositioning — COT positioning for a contract
• GetLatestCftcData — latest COT snapshot
• SearchCftcMarkets — search tracked contracts

Volatility (CBOE)

• GetPutCallRatios — put/call ratios
• GetVixHistory — VIX daily OHLC

FDA calendar

• GetFdaCatalysts — scheduled FDA advisory-committee meetings

Congressional trading

• GetCongressionalTrades — trades for a ticker
• GetMemberTrades — a member's trades
• GetMemberNetWorth — member net worth history
• SearchCongressMembers — search members

Short data (FINRA)

• GetShortVolume — daily short volume
• GetShortInterest — bi-monthly short interest
• GetShortInterestSnapshot — market-wide snapshot
• GetLargestShortVolume — largest daily short volume
• GetShortSqueezeScores — composite squeeze scores
• GetOffExchangeVolume — dark-pool/OTC volume

Stock prices

• GetStockPrices — daily OHLCV (split-adjusted)
• GetLatestPrices — latest close/change/volume
• GetStochasticOscillator — stochastic oscillator (%K/%D)
• GetAverageTrueRange — average true range (ATR)
• GetOnBalanceVolume — on-balance volume (OBV)
• GetBollingerBands — Bollinger Bands

Vector Embeddings (advanced, opt-in)

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

docker compose --profile embedding up

This adds:

Without the embedding profile, BM25 full-text search via ParadeDB still works out of the box — vector search is purely additive.

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

Screenshots

Contributing

See CONTRIBUTING.md for development setup, project architecture, and how to extend the platform. Contributors must sign the Contributor License Agreement — this is handled automatically by a bot when you open a pull request.

License

AGPL-3.0

Author

Daniel Oliveira