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

1# FinBrain MCP&nbsp;<!-- omit in toc -->
2 
3[![PyPI version](https://img.shields.io/pypi/v/finbrain-mcp.svg)](https://pypi.org/project/finbrain-mcp/)
4[![CI](https://github.com/ahmetsbilgin/finbrain-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ahmetsbilgin/finbrain-mcp/actions/workflows/ci.yml)
5[![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
6 
7> **Requires Python 3.10+**
8 
9A **Model Context Protocol (MCP)** server that exposes FinBrain datasets to AI clients (Claude Desktop, VS Code MCP extensions, etc.) via simple tools.  
10Backed by the official **`finbrain-python`** SDK.
11 
12- Package name: **`finbrain-mcp`**
13 
14- CLI entrypoint: **`finbrain-mcp`**
15 
16- Documentation: **[finbrain.tech/integrations/mcp](https://finbrain.tech/integrations/mcp/)**
17 
18----------
19 
20## Features
21 
22### AI-Powered Price Predictions
23 
24Access FinBrain's machine learning price forecasts with daily (10-day) and monthly (12-month) horizons. Includes mean predictions with 95% confidence intervals.
25 
26### News Sentiment Analysis
27 
28Track aggregated sentiment scores derived from financial news coverage. Monitor how market sentiment shifts over time for any ticker.
29 
30### Alternative Data
31 
32- **LinkedIn Metrics** — Employee count and follower trends as company health indicators
33- **App Store Ratings** — Mobile app performance data for consumer-facing companies
34- **Options Flow** — Put/call ratios and volume to gauge market positioning
35 
36### Institutional & Insider Activity
37 
38- **US Congress Trades** — Stock transactions disclosed by House representatives and Senators
39- **Insider Transactions** — SEC Form 4 filings showing executive buys and sells
40- **Analyst Ratings** — Wall Street coverage and price target changes
41 
42----------
43 
44## What you get
45 
46- ⚡️ **Local** MCP server (no proxying) using your **own FinBrain API key**
47 
48- 🧰 Tools (JSON by default, CSV optional) with paging
49 
50  - `health`
51 
52  - `available_markets`, `available_tickers`
53 
54  - `predictions_by_market`, `predictions_by_ticker`
55 
56  - `news_sentiment_by_ticker`
57 
58  - `app_ratings_by_ticker`
59 
60  - `analyst_ratings_by_ticker`
61 
62  - `house_trades_by_ticker`, `senate_trades_by_ticker`
63 
64  - `insider_transactions_by_ticker`
65 
66  - `linkedin_metrics_by_ticker`
67 
68  - `options_put_call`
69 
70- 🧹 Consistent, model-friendly shapes (we normalize raw API responses)
71 
72- 🔑 Multiple ways to provide your API key: env var, file
73 
74----------
75 
76## Install
77 
78### Option A — Standard install (pip)
79 
80```bash
81# macOS / Linux / Windows
82pip install --upgrade finbrain-mcp
83```
84 
85### Option B — Dev install (editable)
86 
87```bash
88# from repo root
89python -m venv .venv
90source .venv/bin/activate # Windows: .\.venv\Scripts\activate
91pip install -e ".[dev]"
92```
93 
94> Keep **pip** (prod) and your **venv** (dev) separate to avoid path mix-ups.
95 
96### Option C — Docker
97 
98```bash
99# Build the image
100docker build -t finbrain-mcp:latest .
101 
102# Run with your API key
103docker run --rm -e FINBRAIN_API_KEY="YOUR_KEY" finbrain-mcp:latest
104```
105 
106> See [DOCKER.md](DOCKER.md) for detailed Docker usage instructions.
107 
108----------
109 
110## Configure your FinBrain API key
111 
112### A) In your MCP client config (recommended / most reliable)
113 
114Put 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.
115 
116#### Claude Desktop (pip install)
117 
118```json
119{
120  "mcpServers": {
121    "finbrain": {
122      "command": "finbrain-mcp",
123      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
124    }
125  }
126}
127```
128 
129### B) Environment variable
130 
131This works too, but note you must restart the client after setting it so the new value is inherited.
132 
133```bash
134# macOS/Linux
135export FINBRAIN_API_KEY="YOUR_KEY"
136 
137# Windows (PowerShell, current session)
138$env:FINBRAIN_API_KEY="YOUR_KEY"
139 
140# Windows (persistent for new processes)
141setx FINBRAIN_API_KEY "YOUR_KEY"
142# then fully quit and reopen your MCP client (e.g., Claude Desktop)
143```
144 
145>**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.
146----------
147 
148## Run the server
149 
150> **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.
151 
152- If installed (pip):
153 
154    `finbrain-mcp`
155 
156- From a dev venv:
157 
158    `python -m finbrain_mcp.server`
159 
160Quick health check without an MCP client:
161 
162```python
163python - <<'PY'
164import json
165from finbrain_mcp.tools.health import health
166print(json.dumps(health(), indent=2))
167PY
168```
169 
170----------
171 
172## Connect an AI client
173 
174> **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.
175 
176### Claude Desktop
177 
178Edit your config:
179 
180- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
181 
182- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
183 
184- Linux: `~/.config/Claude/claude_desktop_config.json`
185 
186**Pip install (published package):**
187 
188```json
189{
190  "mcpServers": {
191    "finbrain": {
192      "command": "finbrain-mcp",
193      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
194    }
195  }
196}
197 
198```
199 
200**macOS tip (full path):**
201 
202If `"command": "finbrain-mcp"` doesn’t work, find the absolute path and use that instead.
203 
204```bash
205which finbrain-mcp    # macOS/Linux
206# (Windows: where finbrain-mcp)
207```
208 
209**Claude config with full path (macOS example):**
210 
211```json
212{
213  "mcpServers": {
214    "finbrain": {
215      "command": "/full/path/to/finbrain-mcp",
216      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
217    }
218  }
219}
220```
221 
222**Dev venv (run the module explicitly):**
223 
224```json
225{
226  "mcpServers": {
227    "finbrain-dev": {
228      "command": "C:\\Users\\you\\path\\to\\repo\\.venv\\Scripts\\python.exe",
229      "args": ["-m", "finbrain_mcp.server"],
230      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
231    }
232  }
233}
234```
235 
236**Docker:**
237 
238```json
239{
240  "mcpServers": {
241    "finbrain": {
242      "command": "docker",
243      "args": ["run", "-i", "--rm", "finbrain-mcp:latest"],
244      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
245    }
246  }
247}
248```
249 
250> After editing, **quit & reopen Claude**.
251 
252### VS Code (MCP)
253 
2541. Open the Command Palette → **“MCP: Open User Configuration”**.  
255   This opens your `mcp.json` (user profile).
2562. Add the server under the **`servers`** key:
257 
258    ```json
259    {
260      "servers": {
261        "finbrain": {
262          "command": "finbrain-mcp",
263          "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
264        }
265      }
266    }
267    ```
268 
2693. In Copilot Chat, enable Agent Mode to use MCP tools.
270 
271----------
272 
273## What can you ask the agent?
274 
275You don’t need to know tool names—just ask in plain English. Examples:
276 
277- **Predictions**
278  - “Get FinBrain’s **daily predictions** for **AMZN**.”
279  - “Show **monthly predictions** (12-month horizon) for **AMZN**.”
280 
281- **News sentiment**
282  - “What’s the **news sentiment** for **AMZN** **from 2025-01-01 to 2025-03-31** (limit 50)?”
283  - “Export **AMZN** news sentiment for **2025 YTD** **as CSV**.”
284 
285- **App ratings**
286  - “Fetch **app store ratings** for **AMZN** between **2025-01-01** and **2025-06-30**.”
287 
288- **Analyst ratings**
289  - “List **analyst ratings** for **AMZN** in **Q1 2025**.”
290 
291- **Congressional trades**
292  - "Show **recent House trades** involving **AMZN**."
293  - "Show **recent Senate trades** involving **META**."
294 
295- **Insider transactions**
296  - “Recent **insider transactions** for **AMZN**?”
297 
298- **LinkedIn metrics**
299  - “Get **LinkedIn employee & follower counts** for **AMZN** (last 12 months).”
300 
301- **Options (put/call)**
302  - “What’s the **put/call ratio** for **AMZN** over the **last 60 days**?”
303 
304- **Availability**
305  - “Which **markets** are available?”
306  - “List **tickers** in the **daily** predictions universe.”
307 
308> **Notes**
309>
310> - Date format: `YYYY-MM-DD`.
311> - Time-series endpoints return the **most recent N** points by default—say “limit 200” to get more.
312> - Predictions horizon: **daily** (10-day) or **monthly** (12-month).
313> - Say “**as CSV**” to receive CSV instead of JSON.
314 
315----------
316 
317## Development
318 
319```bash
320# setup
321python -m venv .venv
322source .venv/bin/activate # Windows: .\.venv\Scripts\activate
323pip install -e ".[dev]"  # run tests pytest -q
324```
325 
326### Project structure (high level)
327 
328```text
329finbrain-mcp
330├─ README.md
331├─ pyproject.toml
332├─ LICENSE
333├─ .github/
334├─ examples/
335├─ src/
336│  └─ finbrain_mcp/
337│     ├─ __init__.py
338│     ├─ server.py                # MCP server entrypoint
339│     ├─ registry.py              # FastMCP instance
340│     ├─ client_adapter.py        # wraps finbrain-python; calls normalizers
341│     ├─ auth.py                  # resolves API key (env var)
342│     ├─ settings.py              # tweakable defaults (e.g., series limits)
343│     ├─ utils.py                 # helpers (latest_slice, CSV, DF->records)
344│     ├─ normalizers/             # endpoint-specific shapers
345│     └─ tools/                   # MCP tool functions (registered & testable)
346└─ tests/                         # pytest suite with a fake SDK
347```
348 
349----------
350 
351## Troubleshooting
352 
353- **`ENOENT`** (can’t start server)
354 
355  - Wrong path in client config. Use the venv’s **exact** path:
356 
357    - `…\.venv\Scripts\python.exe` + `["-m","finbrain_mcp.server"]`, or
358 
359    - `…\.venv\Scripts\finbrain-mcp.exe`
360 
361- **`FinBrain API key not configured`**
362 
363  - Put `FINBRAIN_API_KEY` in the client’s `env` block **or**
364 
365  - `setx FINBRAIN_API_KEY "YOUR_KEY"` and fully restart the client.
366 
367- **Mixing dev & prod installs**
368 
369  - Keep **pip** (prod) and **venv** (dev) separate.
370 
371  - In configs, point to one or the other—not both.
372 
373----------
374 
375## License
376 
377MIT (see `LICENSE`).
378 
379----------
380 
381## Acknowledgements
382 
383- Built on Model Context Protocol and **FastMCP**.
384 
385- Uses the official **`finbrain-python`** SDK.
386 
387----------
388 
389© 2026 FinBrain Technologies — Built with ❤️ for the quant community.
390