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.

• 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

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

Available Tools

The MCP server exposes the following tools to AI assistants:

Tool	Description
health	Check server status
available_markets	List all available markets
available_tickers	List tickers for a prediction type
predictions_by_market	Get predictions for all tickers in a market
predictions_by_ticker	Get AI price predictions for a ticker
news_sentiment_by_ticker	Get news sentiment scores
app_ratings_by_ticker	Get app store ratings
analyst_ratings_by_ticker	Get Wall Street analyst ratings
house_trades_by_ticker	Get US House Representatives trades
senate_trades_by_ticker	Get US Senate trades
insider_transactions_by_ticker	Get SEC Form 4 insider transactions
linkedin_metrics_by_ticker	Get LinkedIn employee/follower data
options_put_call	Get put/call ratio data

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

News Sentiment

• “What’s the news sentiment for AMZN from 2025-01-01 to 2025-03-31?”
• “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?”

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

Availability

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

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