Equibles

# Equibles [](https://github.com/daniel3303/Equibles/actions/workflows/ci.yml) [](https://github.com/daniel3303/Equibles/actions/workflows/codeql.yml) [](https://codecov.io/github/daniel3303/Equibles) [](LICENSE) [](https://dotnet.microsoft.com/) [](docker-compose.yml) [](docker-compose.yml) [](https://modelcontextprotocol.io) 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](https://equibles.com). See [`docs/`](docs/README.md) for the user guide and technical documentation. ## What's Included | Domain | Data Source | Description | |--------|------------|-------------| | **SEC Filings** | SEC EDGAR | 10-K, 10-Q, 8-K annual/quarterly/current reports with full-text search | | **Financial Statements** | SEC XBRL | Parsed income statement, balance sheet, and cash flow facts per fiscal period | | **Holdings** | SEC 13F-HR | Institutional ownership — who owns what, how much, and trend over time | | **Fund Filings** | SEC NPORT / N-CEN / Form D | Fund portfolio holdings, registered-fund operations (service providers), and exempt offerings (private placements) | | **Investment Advisers** | SEC Form ADV | SEC-registered advisers — assets under management, main office, employee count, fee structure | | **Insider Trading** | SEC Form 3/4/144 | Director, officer, and 10% owner transactions, plus proposed (Form 144) sales | | **Congressional Trading** | House/Senate disclosures | Stock trades by members of Congress | | **Short Data** | SEC / FINRA | Fails-to-deliver (SEC), daily short volume and short interest (FINRA) | | **Economic Indicators** | FRED (Federal Reserve) | Interest rates, inflation, employment, GDP, yield spreads, and more | | **Stock Prices** | Yahoo Finance | Daily OHLCV prices with technical indicators (SMA, RSI, MACD) | | **Futures Positioning** | CFTC | Commitments of Traders (COT) data for 30+ futures contracts | | **Market Indicators** | CBOE | VIX volatility index (1990+) and put/call ratios by category | ## Quick Start ### Docker Compose (recommended) The fastest way to get everything running. Requires Docker. ```bash 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) | 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](https://gateway.finra.org/app/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](https://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 # .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 # .env — start syncing from 2024 instead of 2020 Worker__MinSyncDate=2024-01-01 ``` **Embedding (opt-in):** | Setting | Default | Description | |---------|---------|-------------| | `Embedding__Enabled` | `false` | Set to `true` to enable vector embedding generation | | `Embedding__BaseUrl` | — | Ollama or OpenAI-compatible endpoint (e.g., `http://localhost:11434`) | | `Embedding__ModelName` | — | Model name (e.g., `bge-m3`) | | `Embedding__BatchSize` | `10` | Texts per embedding batch | **Update notifications (optional):** | Setting | Default | Description | |---------|---------|-------------| | `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. | **Authentication (optional):** | Setting | Default | Description | |---------|---------|-------------| | `AUTH_USERNAME` | — | Web portal username (auth disabled if empty) | | `AUTH_PASSWORD` | — | Web portal password (auth disabled if empty) | | `MCP_API_KEY` | — | MCP server API key (auth disabled if empty) | 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:** ```bash git pull docker compose up -d --build ``` **From source:** ```bash git pull dotnet build Equibles.sln ``` Database migrations are applied automatically on startup. Review the [changelog](CHANGELOG.md) 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) ### 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` ```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: ```bash 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` ```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). ## 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 BGE-M3 model (~1.2GB). ```bash docker compose --profile embedding up ``` This adds: | Service | Port | Description | |---------|------|-------------| | **embedding** | 11434 | Ollama server with BGE-M3 model | | **worker-embedding** | — | Worker with embedding generation enabled | Without the embedding profile, BM25 full-text search via ParadeDB still works out of the box — vector search is purely additive. ## Screenshots <table> <tr> <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> <td width="50%"><strong>Stocks</strong><br><img alt="Stocks page with search and ticker listing" src="docs/screenshots/stocks-list.png"></td> </tr> <tr> <td width="50%"><strong>Economic Data</strong><br><img alt="Economic indicators grouped by category" src="docs/screenshots/economy.png"></td> <td width="50%"><strong>Economic Indicator Detail</strong><br><img alt="Federal Funds Rate chart and observations" src="docs/screenshots/economy-detail.png"></td> </tr> </table> ## Contributing 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. ## License [AGPL-3.0](LICENSE) ## Author Daniel Oliveira [](https://danielapoliveira.com/) [](https://x.com/daniel_not_nerd) [](https://www.linkedin.com/in/daniel-ap-oliveira/)