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

Video Tutorial

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

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

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

Available Tools

The MCP server exposes 32 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	AI price predictions 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
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

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

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 2025-01-01 and 2025-06-30.”

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?”

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