Metadata-Version: 2.4
Name: finbrain-mcp
Version: 0.2.7
Summary: Open-source FinBrain MCP server (SDK-first via finbrain-python)
Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp<4,>=3
Requires-Dist: pydantic>=2
Requires-Dist: finbrain-python>=0.2.8
Provides-Extra: http
Requires-Dist: requests>=2; extra == "http"
Requires-Dist: pandas>=2; extra == "http"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pandas-stubs>=2.2.2.240603; extra == "dev"
Dynamic: license-file

# FinBrain MCP&nbsp;<!-- omit in toc -->

[![PyPI version](https://img.shields.io/pypi/v/finbrain-mcp.svg)](https://pypi.org/project/finbrain-mcp/)
[![CI](https://github.com/ahmetsbilgin/finbrain-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ahmetsbilgin/finbrain-mcp/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-MIT-brightgreen)](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](https://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)

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

### Option B — Dev install (editable)

```bash
# 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

```bash
# 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](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)

```json
{
  "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.

```bash
# 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
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):**

```json
{
  "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.

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

**Claude config with full path (macOS example):**

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

**Dev venv (run the module explicitly):**

```json
{
  "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:**

```json
{
  "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:

    ```json
    {
      "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

```bash
# 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)

```text
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.
