Finbrain MCP

What ahmetsbilgin/finbrain-mcp MCP server does

The ahmetsbilgin/finbrain-mcp MCP server connects MCP-compatible AI clients to FinBrain datasets through a locally run server. It is intended for financial research workflows that need structured responses instead of manually browsing individual data sources. The package supports Python 3.10 and newer and is published as finbrain-mcp.

Available data includes machine-learning price forecasts, recent company news, historical news sentiment, analyst ratings, and several alternative-data categories. The alternative datasets cover LinkedIn employee and follower measures, mobile app ratings, options put/call activity, Reddit ticker mentions, government contracts, and patent filings. Institutional and insider coverage includes House and Senate transactions, corporate lobbying records, SEC Form 4 transactions, and analyst price-target changes.

Responses are normalized into consistent shapes for model use. Results use JSON by default, support paging, and can optionally be returned as CSV. Several records include a company CIK as a text value, preserving leading zeroes for joins with SEC-keyed systems.

How it works

The MCP client starts the local finbrain-mcp process and communicates with its tools. The server sends requests to FinBrain through the official finbrain-python SDK, using the API key found in the process environment. Claude Desktop and VS Code MCP extensions are identified as supported client contexts in the project material.

The tool surface includes health and discovery operations such as health, available_markets, available_tickers, and available_regions. Ticker-specific operations retrieve predictions, news, sentiment, app ratings, analyst ratings, trading activity, lobbying, insider transactions, LinkedIn metrics, options flow, Reddit mentions, contracts, and patents. Screener tools query groups of stocks for sentiment, ratings, news, trading, and alternative-data signals.

App-rating results have two relevant layers: a blended date series and an apps summary. To investigate one company app, inspect the summary and use its app_id for that app's observations. An unrecognized ID returns available IDs rather than an empty result.

Setup and configuration

Install the published package with pip:

pip install --upgrade finbrain-mcp

Set FINBRAIN_API_KEY before launching the client, or place it in the MCP client's server configuration. The README specifically recommends putting the key in the client's env block when environment inheritance is unreliable. After changing a shell environment variable, restart the MCP client so the new process receives it.

A configured client can start the installed finbrain-mcp entry point automatically. For manual checks, run finbrain-mcp; a development checkout can instead use python -m finbrain_mcp.server. Docker usage is also documented, including passing the API key into the container.

Tools and capabilities

The ahmetsbilgin/finbrain-mcp MCP server provides tools for:

• Daily ten-day and monthly twelve-month price predictions, including means and 95% confidence intervals.
• Ticker news, recent news, sentiment history, and news screening.
• Analyst coverage and rating screens.
• House and Senate trade queries and screens.
• Insider transactions and corporate lobbying records.
• LinkedIn, app-store, options, Reddit, government-contract, and patent data.
• Market, ticker, and region discovery.

Limitations and notes

The server depends on access to FinBrain and therefore cannot operate without a valid FINBRAIN_API_KEY. It is local rather than a hosted MCP endpoint, so the client must be able to run Python software or the documented Docker image. The supplied material does not specify API pricing, rate limits, or data freshness for each dataset.

For app ratings, the blended series represents the largest app observed on each store for a date, not every app published by the company. Use the app summary and an app ID when the question concerns a particular application. CIK values may be null when entity resolution is unavailable, and should be treated as strings when present.