equity-intel-mcp

Institutional-grade equity analysis for any LLM, over the Model Context Protocol.

Most "stock" integrations just echo a price. This one gives an AI agent the signals professionals actually look at — insider buying from SEC filings, what renowned value investors are holding, analyst consensus, options-implied moves, and valuation — and blends them into a single, confidence-weighted verdict.

It runs entirely on free / public data (Yahoo Finance, SEC EDGAR, Dataroma), fails gracefully when a source is missing, and never fabricates a signal it doesn't have.

# Equity Intelligence — MSFT

## Verdict: Neutral → HOLD
[........|#.......] +11/100  · confidence 69%  · 5 source(s)

| Source        | Signal       | Score  | Conf | Weight |
|---------------|--------------|-------:|-----:|-------:|
| insider       | Bearish      |   -77  |  70% |   0.25 |
| superinvestor | Lean bullish |   +33  | 100% |   0.30 |
| analysts      | Bullish      |   +64  |  75% |   0.15 |
| valuation     | Bullish      |   +91  |  60% |   0.09 |
| options       | Lean bullish |   +19  |  40% |   0.04 |

- insider: Insiders net selling $13.5M over 180d (62 filings).
- superinvestor: 38 tracked superinvestors hold MSFT; 19 buys / 18 sells.
- analysts: 66 analysts: 23 strong buy / 38 buy / 5 hold.
- valuation: Fair value ~$569 vs $391 (+46% upside); health 84/100.
- options: 1-month implied move +/-7.6%; put/call OI 0.53.

Tools

Every tool returns Markdown (human-readable, default) or JSON (response_format="json") for programmatic use.

Quick start

git clone https://github.com/cstamigo-droid/equity-intel-mcp equity-intel-mcp
cd equity-intel-mcp
python -m venv .venv && .venv\Scripts\activate     # Windows
pip install -r requirements.txt

copy .env.example .env        # then edit .env (set EDGAR_IDENTITY)
python -m equity_intel_mcp    # starts the MCP server over stdio

Smoke test (hits the live sources and prints each signal):

python tests/test_smoke.py AAPL

Configure (.env)

# Required by SEC fair-access policy — any "Name email@example.com"
EDGAR_IDENTITY=Your Name you@example.com
# Required by equity_analyst_consensus (free key at finnhub.io)
FINNHUB_API_KEY=your-key-here

Use it in Claude Desktop

Add this to claude_desktop_config.json (%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS), then restart Claude Desktop:

{
  "mcpServers": {
    "equity-intel": {
      "command": "python",
      "args": ["-m", "equity_intel_mcp"],
      "cwd": "C:/path/to/equity-intel-mcp",
      "env": { "EDGAR_IDENTITY": "Your Name you@example.com" }
    }
  }
}

Then just ask Claude: "Give me a full read on NVDA" or "Are insiders buying PLTR?"

Why it's built this way

• Uniform signal contract. Every source returns the same shape (score -100..+100, confidence 0..1, data, summary). That's what lets an LLM reason across heterogeneous evidence instead of parsing five formats.
• Graceful degradation. A stock with no Form 4 activity returns "no signal", not a fake bearish score. Missing data lowers confidence; it never invents a call.
• Confidence-weighted blending. The composite weights each source by its importance × its own confidence, so thin signals don't outvote strong ones.
• Resilient + cached. Short per-source TTL caches avoid hammering rate-limited endpoints when an agent calls several tools on the same ticker in one turn.

See ROADMAP.md for what's next.

Disclaimer

For research and educational use only. Not investment advice. Data comes from third-party public sources and may be delayed or incomplete. Do your own due diligence.

License

MIT