stock-market-mcp-server

# Equibles — Stock Market & Financial Data MCP Server

111 MCP tools for AI agents like Claude, ChatGPT and Cursor: SEC filings, fundamentals, 13F institutional holdings, insider and congressional trades, earnings call transcripts, options chains, live quotes, IPO filings, short interest, macro data, and your own portfolio. Free hosted tier, or self-host the open-source stack.

[![Discovery repo: MIT](https://img.shields.io/badge/discovery%20repo-MIT-blue.svg)](LICENSE)
[![Tools](https://img.shields.io/badge/tools-111-brightgreen.svg)](#tools)
[![Free tier](https://img.shields.io/badge/free%20tier-100%20req%2Fday-orange.svg)](#pricing--rate-limits)
[![equibles.com](https://img.shields.io/badge/equibles.com-visit-6366f1.svg)](https://equibles.com)

## What is this?

The Model Context Protocol (MCP) lets AI assistants call external data tools instead of guessing from training data. Equibles exposes US stock market and financial data as an MCP server: use it hosted at `https://mcp.equibles.com/mcp` (free API key, or OAuth with no key at all), or run it yourself from the open-source stack. Everything is parsed from the primary sources (SEC EDGAR, FINRA, FRED, CFTC, CBOE, USAspending, company IR sites), not from third-party estimates.

## Licenses

This discovery repository's documentation and metadata use the [MIT license](LICENSE). The self-hosted server implementation is in [daniel3303/Equibles](https://github.com/daniel3303/Equibles) under [AGPL-3.0](https://github.com/daniel3303/Equibles/blob/main/LICENSE). The hosted service is governed by the [Equibles Terms of Service](https://equibles.com/legal/terms).

## Quickstart (hosted, 30 seconds)

1. Create a free account at [equibles.com](https://equibles.com) — no credit card required.
2. Create an API key at [`https://equibles.com/dashboard/apikeys`](https://equibles.com/dashboard/apikeys). It starts with `eq_` and is shown once, so copy it right away.
3. Connect your client with the URL `https://mcp.equibles.com/mcp` (see below).

ChatGPT and Claude (web and Desktop) can skip the key entirely and sign in over OAuth.

## Connect your AI client

### Plugin packages

This repository includes an [Agent Plugins](https://agent-plugins.org/specification) package for compatible clients such as Cursor (`plugin.json` and `mcp.json`), a Grok Build package (`.grok-plugin/plugin.json` and `.mcp.json`), and a Gemini CLI extension (`gemini-extension.json`). These files configure the hosted MCP endpoint; they do not contain the server implementation. Marketplace availability is separate from these installable packages.

The packages use client-managed OAuth through `https://mcp.equibles.com/mcp?auth=oauth`. The query parameter requests authentication during discovery, so the client prompts for sign-in before attempting a data query. Sign in to your Equibles account when prompted. In Gemini CLI, use `/mcp auth equibles` if needed. If your client does not support OAuth, use the API-key configuration below instead.

Install the Gemini CLI extension from this repository:

```bash
gemini extensions install https://github.com/daniel3303/stock-market-mcp-server
```

For a local checkout of this package, use `gemini extensions link /absolute/path/to/stock-market-mcp-server`. After reviewing the package, Grok Build users can run `grok plugin install /absolute/path/to/stock-market-mcp-server --trust`, then `grok plugin enable equibles` and start a new session.

The only MCP endpoint configured by these packages is `https://mcp.equibles.com/mcp?auth=oauth`. OAuth discovery and sign-in use `https://equibles.com/`. Queries and explicitly requested portfolio changes are sent to Equibles under the signed-in account. Keep the client's normal tool confirmations enabled: portfolio tools can create, change, or delete your saved holdings, and feedback tools send reports to Equibles. The packages contain no executable scripts, lifecycle hooks, embedded credentials, or telemetry code. Hosted usage is subject to account entitlements and the [service terms](https://equibles.com/legal/terms).

### Cline

Create an Equibles account and an API key using the Quickstart above. In Cline, open **MCP Servers → Configure MCP Servers** and merge this entry into the `mcpServers` object, replacing `eq_your_api_key` with your own key:

```json
{
  "mcpServers": {
    "equibles": {
      "type": "streamableHttp",
      "url": "https://mcp.equibles.com/mcp",
      "headers": { "Authorization": "Bearer eq_your_api_key" },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

Keep the key in your local client configuration and never commit it. Save the configuration, confirm Equibles is connected, and ask Cline to call `GetMarketStatus` as a read-only connection check. If authentication fails, check the key or sign in through the client's OAuth flow. See the [Cline MCP documentation](https://docs.cline.bot/mcp/mcp-overview) for client setup.

### Claude Desktop / Claude web (claude.ai)

Settings → Connectors → Add custom connector → URL `https://mcp.equibles.com/mcp` → sign in over OAuth (no key needed).

Key alternative: use the URL `https://mcp.equibles.com/mcp?api_key=eq_your_api_key`.

### Claude Code

```bash
claude mcp add --transport http equibles https://mcp.equibles.com/mcp
```

Then run `/mcp` and choose **Authenticate** to sign in over OAuth.

Key alternative:

```bash
claude mcp add-json equibles '{"type":"http","url":"https://mcp.equibles.com/mcp","headers":{"Authorization":"Bearer eq_your_api_key"}}' --scope user
```

### ChatGPT

Add a developer-mode connector with URL `https://mcp.equibles.com/mcp` and complete the OAuth sign-in (or use the `?api_key=eq_your_api_key` URL).

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{ "mcpServers": { "equibles": { "url": "https://mcp.equibles.com/mcp", "headers": { "Authorization": "Bearer eq_your_api_key" } } } }
```

### VS Code (Copilot)

```bash
code --add-mcp '{"name":"equibles","type":"http","url":"https://mcp.equibles.com/mcp"}'
```

Or add a `.vscode/mcp.json` with a `"servers"` object using the same URL and `Authorization` header shape:

```json
{ "servers": { "equibles": { "type": "http", "url": "https://mcp.equibles.com/mcp", "headers": { "Authorization": "Bearer eq_your_api_key" } } } }
```

### Any MCP client

Use the HTTP transport with URL `https://mcp.equibles.com/mcp`, authenticating with an `Authorization: Bearer eq_...` header or a `?api_key=eq_...` query parameter.

After connecting, see the full per-client guides at [https://equibles.com/docs/mcp](https://equibles.com/docs/mcp).

## Example prompts

- "Which hedge funds bought the most NVIDIA last quarter?"
- "Summarize the risk factors in Tesla's latest 10-K."
- "Show recent insider selling at Microsoft, and has any member of Congress traded it this year?"
- "What did NVIDIA guide for next quarter, and what KPIs did it report?"
- "Which stocks have the highest short-squeeze scores today?"
- "Screen for profitable software stocks under a 20 P/E."
- "What's the latest CPI and unemployment rate?"

## Tools

111 tools, grouped by dataset.

### SEC filings search & full-text RAG

| Tool | Description |
|---|---|
| SearchDocuments | Hybrid keyword + semantic search across all companies' SEC filings. |
| SearchCompanyDocuments | Hybrid search of one company's filings by ticker. |
| SearchDocument | Hybrid search within a single filing. |
| ListCompanyDocuments | Browse available SEC filings and transcripts for a company. |
| SearchDocumentKeyword | Keyword search within one filing. |
| ReadDocumentLines | Read a line range from a filing. |

### Financial statements & fundamentals (XBRL)

| Tool | Description |
|---|---|
| GetFinancialStatement | Income statement, balance sheet, or cash-flow statement for a fiscal period (XBRL). |
| GetFinancialFact | One financial concept over time. |
| CompareFinancialFact | Compare a concept across companies. |
| GetRevenueBreakdown | Revenue by segment, geography, and product (dimensional XBRL). |

### 13F institutional holdings & hedge fund portfolios

| Tool | Description |
|---|---|
| GetFundCloneBacktest | Backtest cloning an institutional filer's 13F portfolio vs a market benchmark. |
| GetTopHolders | Top institutional holders of a stock from SEC 13F-HR filings, ranked by shares held. |
| GetOwnershipHistory | Historical trend of institutional ownership across quarters. |
| GetInstitutionPortfolio | A specific institution's portfolio from its 13F-HR. |
| SearchInstitutions | Search institutional investors by name or SEC CIK. |
| GetTopBuyersSellers | Institutions with the biggest share additions/reductions on a stock this quarter. |
| GetMarketWide13FActivity | Market-wide 13F leaderboards (top buys/sells/new/sold-out) for a quarter. |
| GetMostHeldStocks | Stocks ranked by institutional 13F breadth. |
| GetInstitutionSummary | Portfolio summary for a 13F filer (value, concentration, turnover). |
| GetInstitutionSectorAllocation | An institution's 13F allocation by sector. |
| GetInstitutionQuarterlyActivity | Initiated / increased / reduced / exited activity vs the prior quarter. |
| GetFundOverlap | 13F portfolio overlap between two institutions. |
| GetConsensusHoldings | Consensus portfolio of 2–25 institutions. |

### Insider trading (Form 3/4/5 & Form 144)

| Tool | Description |
|---|---|
| GetInsiderTransactions | Recent insider transactions from SEC Form 3/4/5. |
| GetInsiderOwnership | Insider ownership summary, ranked by shares held. |
| GetProposedSales | Proposed insider sales from SEC Form 144. |
| SearchInsiders | Search corporate insiders by name. |
| GetInsiderSentimentScores | Stocks with the highest composite 0–100 insider-sentiment score. |

### Congressional stock trading

| Tool | Description |
|---|---|
| GetCongressionalTrades | Congressional trades for a ticker. |
| GetMemberTrades | A member's disclosed trades. |
| GetMemberNetWorth | A member's net worth history from disclosures. |
| SearchCongressMembers | Search