ahmetsbilgin/finbrain-mcp

PyPI version CI License

Requires Python 3.10+

A Model Context Protocol (MCP) server that exposes FinBrain datasets to AI clients (Claude Desktop, VS Code MCP extensions, etc.) via simple tools. Backed by the official finbrain-python SDK (v2 API).

• Package name: finbrain-mcp

• CLI entrypoint: finbrain-mcp

• Documentation: finbrain.tech/integrations/mcp

---

Features

AI-Powered Price Predictions

Access FinBrain's machine learning price forecasts with daily (10-day) and monthly (12-month) horizons. Includes mean predictions with 95% confidence intervals.

News & Sentiment Analysis

Browse recent news articles for any ticker, or track aggregated daily sentiment scores over time. Screen news across all tracked stocks.

Alternative Data

• LinkedIn Metrics — Employee count and follower trends as company health indicators
• App Store Ratings — Mobile app performance data for consumer-facing companies
• Options Flow — Put/call ratios and volume to gauge market positioning
• Reddit Mentions — Ticker mention counts across subreddits, collected every 4 hours
• Government Contracts — U.S. government contract awards from USAspending.gov
• Patent Filings — USPTO granted patents mapped to tickers by corporate assignee, with CPC classification

Institutional & Insider Activity

• US Congress Trades — Stock transactions disclosed by House representatives and Senators, with the transaction date and the public disclosure date (so you can measure reporting lag), the beneficial owner of the traded account (member, spouse, dependent child, joint, or an account code), and filed amounts normalized to the statutory STOCK Act brackets with the original filing preserved
• Corporate Lobbying — Lobbying filings with registrant, income, expenses, and issue codes
• Insider Transactions — SEC Form 4 filings showing executive buys and sells
• Analyst Ratings — Wall Street coverage and price target changes

---

What you get

• ⚡️ Local MCP server (no proxying) using your own FinBrain API key

• 🧰 Tools (JSON by default, CSV optional) with paging

  • health

  • available_markets, available_tickers, available_regions

  • predictions_by_market, predictions_by_ticker

  • news_by_ticker, news_sentiment_by_ticker

  • app_ratings_by_ticker

  • analyst_ratings_by_ticker

  • house_trades_by_ticker, senate_trades_by_ticker

  • corporate_lobbying_by_ticker

  • insider_transactions_by_ticker

  • linkedin_metrics_by_ticker

  • options_put_call

  • reddit_mentions_by_ticker

  • government_contracts_by_ticker

  • patent_filings_by_ticker

  • recent_news, recent_analyst_ratings

  • screener_sentiment, screener_analyst_ratings, screener_news

  • screener_insider_trading, screener_house_trades, screener_senate_trades

  • screener_put_call_ratio, screener_linkedin, screener_app_ratings, screener_reddit_mentions, screener_government_contracts, screener_patent_filings

• 🧹 Consistent, model-friendly shapes (we normalize raw API responses)

• 🏛️ insider_transactions_by_ticker, government_contracts_by_ticker, corporate_lobbying_by_ticker, and patent_filings_by_ticker rows carry cik — the company's SEC Central Index Key as of the record, a 10-digit zero-padded string ("0000320193"; keep it text, the leading zeros are part of the identifier), null when the record has no entity resolution. Use it to join rows to SEC-keyed datasets (EDGAR filings, 13F holdings) or a security master

• 🔑 Provide your API key via the FINBRAIN_API_KEY environment variable (a shell env var or your MCP client's env block)

---

Install

Option A — Standard install (pip)

# macOS / Linux / Windows
pip install --upgrade finbrain-mcp

Option B — Dev install (editable)

# from repo root
python -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\activate
pip install -e ".[dev]"

Keep pip (prod) and your venv (dev) separate to avoid path mix-ups.

Option C — Docker

# Build the image
docker build -t finbrain-mcp:latest .

# Run with your API key
docker run --rm -e FINBRAIN_API_KEY="YOUR_KEY" finbrain-mcp:latest

See DOCKER.md for detailed Docker usage instructions.

---

Configure your FinBrain API key

A) In your MCP client config (recommended / most reliable)

Put the key directly in the MCP server entry your client uses (Claude Desktop or a VS Code MCP extension). This guarantees the launched server sees it, even if system env vars aren’t picked up.

Claude Desktop (pip install)

{
  "mcpServers": {
    "finbrain": {
      "command": "finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

B) Environment variable

This works too, but note you must restart the client after setting it so the new value is inherited.

# macOS/Linux
export FINBRAIN_API_KEY="YOUR_KEY"

# Windows (PowerShell, current session)
$env:FINBRAIN_API_KEY="YOUR_KEY"

# Windows (persistent for new processes)
setx FINBRAIN_API_KEY "YOUR_KEY"
# then fully quit and reopen your MCP client (e.g., Claude Desktop)

Tip: If the env var route doesn’t seem to work (common on Windows if the client was already running), use the config JSON env method above—it’s more deterministic.

---

Run the server

Note: You typically don’t need to run the server manually—your MCP client (Claude/VS Code) starts it automatically. Use the commands below only for manual checks or debugging.

• If installed (pip):

  finbrain-mcp

• From a dev venv:

  python -m finbrain_mcp.server

Quick health check without an MCP client:

python - <<'PY'
import json
from finbrain_mcp.tools.health import health
print(json.dumps(health(), indent=2))
PY

---

Connect an AI client

No manual start needed: Claude Desktop and VS Code will launch the MCP server for you based on your config. You only need to run finbrain-mcp yourself for quick sanity checks or debugging.

Claude Desktop

Edit your config:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Pip install (published package):

{
  "mcpServers": {
    "finbrain": {
      "command": "finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

macOS tip (full path):

If "command": "finbrain-mcp" doesn’t work, find the absolute path and use that instead.

which finbrain-mcp    # macOS/Linux
# (Windows: where finbrain-mcp)

Claude config with full path (macOS example):

{
  "mcpServers": {
    "finbrain": {
      "command": "/full/path/to/finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

Dev venv (run the module explicitly):

{
  "mcpServers": {
    "finbrain-dev": {
      "command": "C:\\Users\\you\\path\\to\\repo\\.venv\\Scripts\\python.exe",
      "args": ["-m", "finbrain_mcp.server"],
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

Docker:

{
  "mcpServers": {
    "finbrain": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "finbrain-mcp:latest"],
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

After editing, quit & reopen Claude.

VS Code (MCP)

1. Open the Command Palette → “MCP: Open User Configuration”.
   This opens your mcp.json (user profile).

2. Add the server under the servers key:

   {
     "servers": {
       "finbrain": {
         "command": "finbrain-mcp",
         "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
       }
     }
   }
   

3. In Copilot Chat, enable Agent Mode to use MCP tools.

---

What can you ask the agent?

You don’t need to know tool names—just ask in plain English. Examples:

• Predictions

  • “Get FinBrain’s daily predictions for AMZN.”
  • “Show monthly predictions (12-month horizon) for AMZN.”
  • “Get market-wide daily predictions for S&P 500 tickers.”

• News

  • “Get recent news articles for AMZN.”
  • “What’s the news sentiment for AMZN from 2025-01-01 to 2025-03-31 (limit 50)?”
  • “Show me the latest news across all S&P 500 stocks.”

• App ratings

  • “Fetch app store ratings for AMZN between 2025-01-01 and 2025-06-30.”

• Analyst ratings

  • “List analyst ratings for AMZN in Q1 2025.”

• Congressional trades

  • “Show recent House trades involving AMZN.”
  • “Show recent Senate trades involving META.”
  • “For NVDA House trades, how long did each member take to disclose the trade?”
  • “Which recent Senate trades were made through a spouse or joint account?”

• Corporate lobbying

  • “Show corporate lobbying filings for AAPL.”
  • “What lobbying firms has MSFT used in 2024 (from 2024-01-01 to 2024-12-31)?”

• Insider transactions

  • “Recent insider transactions for AMZN?”

• LinkedIn metrics

  • “Get LinkedIn employee & follower counts for AMZN (last 12 months).”

• Options (put/call)

  • “What’s the put/call ratio for AMZN over the last 60 days?”

• Reddit mentions

  • “Show Reddit mentions for TSLA over the last week.”
  • “Which subreddits are talking about AAPL the most?”

• Government contracts

  • “Show government contracts awarded to LMT in 2025.”
  • “Which companies have the largest government contract awards?”

• Patent filings

  • “Show recent patent filings for AAPL.”
  • “Which companies have the most granted patents lately?”

• Screeners (cross-ticker)

  • “Screen sentiment across S&P 500 stocks.”
  • “Show the latest analyst ratings across all stocks.”
  • “Screen insider trades across all tickers (limit 50).”
  • “Screen LinkedIn data for US region stocks.”
  • “What are the most mentioned tickers on Reddit right now?”
  • “Which companies are filing the most patents right now?”

• Availability

  • “Which markets are available?”
  • “List tickers in the daily predictions universe.”
  • “Show available regions and their markets.”

Notes

• Date format: YYYY-MM-DD.
• Time-series endpoints return the most recent N points by default—say “limit 200” to get more.
• Predictions horizon: daily (10-day) or monthly (12-month).
• Say “as CSV” to receive CSV instead of JSON.
• No need to specify a market—just use the ticker symbol directly.

---

Development

# setup
python -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\activate
pip install -e ".[dev]"  # run tests pytest -q

Project structure (high level)

finbrain-mcp
├─ README.md
├─ pyproject.toml
├─ LICENSE
├─ .github/
├─ examples/
├─ src/
│  └─ finbrain_mcp/
│     ├─ __init__.py
│     ├─ server.py                # MCP server entrypoint
│     ├─ registry.py              # FastMCP instance
│     ├─ client_adapter.py        # wraps finbrain-python; caches SDK client; calls normalizers
│     ├─ auth.py                  # resolves API key (env var)
│     ├─ utils.py                 # helpers (latest_slice, CSV, DF->records)
│     ├─ normalizers/             # endpoint-specific shapers
│     └─ tools/                   # MCP tool functions (registered & testable)
└─ tests/                         # pytest suite with a fake SDK

---

Troubleshooting

• ENOENT (can’t start server)

  • Wrong path in client config. Use the venv’s exact path:

    • …\.venv\Scripts\python.exe + ["-m","finbrain_mcp.server"], or

    • …\.venv\Scripts\finbrain-mcp.exe

• FinBrain API key not configured

  • Put FINBRAIN_API_KEY in the client’s env block or

  • setx FINBRAIN_API_KEY "YOUR_KEY" and fully restart the client.

• Mixing dev & prod installs

  • Keep pip (prod) and venv (dev) separate.

  • In configs, point to one or the other—not both.

---

License

MIT (see LICENSE).

---

Acknowledgements

• Built on Model Context Protocol and FastMCP.

• Uses the official finbrain-python SDK.

---

© 2026 FinBrain Technologies — Built with ❤️ for the quant community.