# ahmetsbilgin/finbrain-mcp [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/ahmetsbilgin/finbrain-mcp  
**GitHub Stars:** 9  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ahmetsbilgin-finbrain-mcp

## Description
Access institutional-grade alternative financial data directly in your LLM workflows.

## Claude Desktop Quick Installation
Install path inferred — verify against the README before running it. Uses `pipx` (confidence: medium):

```json
"mcpServers": {
  "finbrain-mcp": {
    "command": "pipx",
    "args": ["finbrain-mcp"],
    "env": {
      "FINBRAIN_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `FINBRAIN_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/ahmetsbilgin-finbrain-mcp/readme_