MCP Integration Guide

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 (v0.2.0+, using the v2 API).

• Package name: finbrain-mcp
• CLI entrypoint: finbrain-mcp
• GitHub: github.com/ahmetsbilgin/finbrain-mcp

How It Fits Together

Your side

MCP clients

Whatever your team already uses

• Claude Desktop
• VS Code, Copilot agent mode
• Custom LLM apps and copilots

MCP

Your side

finbrain-mcp

Runs in your environment

• pip install finbrain-mcp, or Docker
• Launched by the client as a local process
• API key from the environment
• 33 tools for the model to call
• JSON by default, CSV on request

HTTPS

Our side

FinBrain v2 API

api.finbrain.tech

• Built on finbrain-python
• 12 datasets, one envelope and one key
• Entitlements and rate limits per key

The server runs where you run it. Your prompts stay inside your environment — only the data request crosses the boundary.

Video Tutorial

Watch how to use FinBrain’s MCP integration for LLM-based stock research:

Features

Price Forecasts

Access FinBrain’s statistical time-series price forecasts with daily (10-day) and monthly (12-month) horizons. Includes mid predictions with calibrated upper and lower bounds.

News Sentiment Analysis

Track aggregated sentiment scores derived from financial news coverage. Monitor how market sentiment shifts over time for any ticker.

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 Reddit investing communities

Institutional & Insider Activity

• US Congress Trades — Stock transactions disclosed by House representatives and Senators
• Insider Transactions — SEC Form 4 filings showing executive buys and sells
• Analyst Ratings — Wall Street coverage and price target changes
• Corporate Lobbying — Federal lobbying disclosures with registrant details and expenditures
• Government Contracts — Federal contract awards from USAspending.gov mapped to tickers
• Patent Filings — USPTO granted patents mapped to tickers, with CPC classification

Available Tools

The MCP server exposes 33 tools to AI assistants:

Discovery & Availability

Tool	Description
health	Check server status and version
available_markets	List all available markets
available_tickers	List tickers for a prediction type
available_regions	List markets grouped by region

Per-Ticker Data

Tool	Description
predictions_by_ticker	Price forecasts with confidence intervals
news_sentiment_by_ticker	Daily sentiment scores over time
news_by_ticker	Recent news articles for a ticker
analyst_ratings_by_ticker	Wall Street analyst ratings and price targets
house_trades_by_ticker	US House Representatives trades
senate_trades_by_ticker	US Senate trades
insider_transactions_by_ticker	SEC Form 4 insider transactions
linkedin_metrics_by_ticker	LinkedIn employee and follower data
app_ratings_by_ticker	App Store and Play Store ratings, plus a summary of every app the company publishes
options_put_call	Put/call ratio and volume data
corporate_lobbying_by_ticker	Corporate lobbying filings (LDA disclosures)
reddit_mentions_by_ticker	Reddit mention counts by subreddit
government_contracts_by_ticker	Federal contract awards mapped to a ticker
patent_filings_by_ticker	USPTO granted patents mapped to a ticker

Cross-Ticker Screeners

Tool	Description
predictions_by_market	Screen predictions across tickers by market or region
screener_sentiment	Screen sentiment across tickers (requires market or region)
screener_analyst_ratings	Screen analyst ratings across tickers
screener_insider_trading	Screen insider trades across tickers
screener_house_trades	Screen House trades across tickers
screener_senate_trades	Screen Senate trades across tickers
screener_news	Screen news across tickers
screener_put_call_ratio	Screen put/call ratios across tickers
screener_linkedin	Screen LinkedIn data across tickers (requires market or region)
screener_app_ratings	Screen app ratings across tickers (requires market or region)
screener_reddit_mentions	Screen Reddit mentions across tickers
screener_government_contracts	Screen government contract awards across tickers
screener_patent_filings	Screen patent filings across tickers

Recent Activity

Tool	Description
recent_news	Latest news articles across all tracked stocks
recent_analyst_ratings	Latest analyst ratings across all tracked stocks

All tools return JSON by default, with optional CSV output.

Installation

pip install finbrain-mcp

Configuration

Claude Desktop

Edit your Claude Desktop config file:

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

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

Linux

Edit ~/.config/Claude/claude_desktop_config.json:

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

After saving the configuration, quit and reopen Claude Desktop.

macOS tip: If "command": "finbrain-mcp" doesn’t work, find and use the full path:

which finbrain-mcp

Then use that path in your config:

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

VS Code

1. Open the Command Palette → “MCP: Open User Configuration”
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.

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

Claude Desktop config for Docker:

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

Example Prompts

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

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 & Sentiment

• “What’s the news sentiment for AMZN from 2025-01-01 to 2025-03-31?”
• “Get recent news articles for AMZN.”
• “Export AMZN news sentiment for 2025 YTD as CSV.”

App Ratings

• “Fetch app store ratings for UBER between 2026-09-01 and 2026-09-30.”
• “Which apps does AAPL publish, and which is the biggest?”
• “Show the rating history of Shazam for AAPL.”

The tool returns the blended company series plus an apps summary — one line per app with its id, name, observation count and latest score. Ask for a specific app and the assistant passes its app_id to get that app’s own series, so a company with a hundred apps does not flood the conversation.

Analyst Ratings

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

Congressional Trades

• “Show recent House trades involving NVDA.”
• “Show recent Senate trades involving META.”

Insider Transactions

• “Recent insider transactions for TSLA?”

Corporate Lobbying

• “Show corporate lobbying filings for AAPL.”
• “Which lobbying firms represent GOOGL?”

Government Contracts

• “Show recent government contracts awarded to LMT.”
• “Which agencies award the most contracts to RTX?”

Patent Filings

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

LinkedIn Metrics

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

Options Put/Call

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

Screeners

• “Screen sentiment across S&P 500 stocks.”
• “Screen insider trading across all tickers.”
• “Screen LinkedIn data for US region stocks.”
• “Screen app ratings for NASDAQ tickers.”

Recent Activity

• “Show the latest news across all tracked stocks.”
• “What are the most recent analyst ratings?”

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

Troubleshooting

Server Not Starting (ENOENT)

Wrong path in client config. Use the exact path:

# Find the path
which finbrain-mcp    # macOS/Linux
where finbrain-mcp    # Windows

API Key Not Configured

Put FINBRAIN_API_KEY in the client’s env block (recommended), or set it as an environment variable:

# macOS/Linux
export FINBRAIN_API_KEY="YOUR_KEY"

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

# Windows (persistent)
setx FINBRAIN_API_KEY "YOUR_KEY"

Then fully restart your MCP client.

Checking Logs

Claude Desktop logs can help diagnose issues:

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

Related Resources

• Python SDK
• API Reference
• Quick Start Guide