# @fffinstill/mcp-server

[![alraico/fffinstill-mcp-server MCP server](https://glama.ai/mcp/servers/alraico/fffinstill-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/alraico/fffinstill-mcp-server)

MCP server for [fffinstill](https://fffinstill.com) — investment analysis for 2,260+ US equities.

Connect Claude Desktop, Cursor, VS Code, or any MCP-compatible AI assistant to fffinstill's stock analysis, screening, macro data, ML earnings predictions, and alternative data tools.

## Features

- **69 tools** — Stock analysis, screening, portfolio analytics, macro indicators, ML predictions, insider/congressional trades, alternative data, risk metrics, 18 academic factor models, and 13 Business-exclusive tools
- **7 resources** — Market signal, macro regime, Fear & Greed, sector overview, company summaries
- **15 prompts** — Pre-built workflows for stock analysis, comparison, screening, macro outlook, portfolio health, alternative data, market dashboard, deep value, risk assessment, growth momentum, income analysis, factor models, insider intelligence

## Quick Start

### 1. Get an API Key

Sign up at [fffinstill.com](https://fffinstill.com) and generate an API key at [Settings → API](https://fffinstill.com/settings/api).

Requires a Founding, Pro, or Business subscription.

### 2. Configure Your AI Client

#### Claude Desktop

Add to `~/.config/claude/claude_desktop_config.json` (Linux/macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "fffinstill": {
      "command": "npx",
      "args": ["-y", "@fffinstill/mcp-server"],
      "env": {
        "FINSTILL_API_KEY": "finstill_xxx_yyy"
      }
    }
  }
}
```

#### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "fffinstill": {
      "command": "npx",
      "args": ["-y", "@fffinstill/mcp-server"],
      "env": {
        "FINSTILL_API_KEY": "finstill_xxx_yyy"
      }
    }
  }
}
```

#### VS Code

Add to `.vscode/mcp.json` in your project root:

```json
{
  "servers": {
    "fffinstill": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fffinstill/mcp-server"],
      "env": {
        "FINSTILL_API_KEY": "finstill_xxx_yyy"
      }
    }
  }
}
```

### 3. Use It

Once configured, your AI assistant can:

- "Analyze AAPL" → calls `getCompanyMetrics`, `getReverseDCF`, `getBeneishScore`, etc.
- "Screen for high-quality tech stocks" → uses the `screen-stocks` prompt
- "Compare NVDA, AMD, and INTC" → calls `compareTickers`
- "What's the macro outlook?" → uses the `macro-outlook` prompt
- "Is MSFT likely to beat earnings?" → uses `earnings-preview` prompt

## CLI Usage

```bash
# With npx (no install)
npx @fffinstill/mcp-server --api-key finstill_xxx_yyy

# With environment variable
FINSTILL_API_KEY=finstill_xxx_yyy npx @fffinstill/mcp-server

# Global install
npm install -g @fffinstill/mcp-server
fffinstill-mcp --api-key finstill_xxx_yyy

# Show help
fffinstill-mcp --help
```

## Tools Reference

### Stock Analysis (16 tools)

| Tool | Description |
|------|-------------|
| `getCompanyMetrics(ticker)` | Full fundamentals: revenue, margins, valuations, quality scores |
| `getAnalystRatings(ticker)` | Consensus, price targets, ratings breakdown |
| `getPriceHistory(ticker, weeks?)` | Weekly prices with returns (default: 52 weeks) |
| `getQuarterlyFinancials(ticker)` | 8 quarters: revenue, margins, ROIC, D/E |
| `getScoreHistory(ticker)` | Composite quality score (7 components) over 12 periods |
| `getReverseDCF(ticker)` | Bear/base/bull fair value scenarios |
| `getBeneishScore(ticker)` | M-Score earnings manipulation detection |
| `getZScoreHistory(ticker)` | Altman Z-Score bankruptcy risk history |
| `getConvictionHistory(ticker)` | Insider conviction trajectory scores (buying patterns) |
| `getMacroSensitivity(ticker)` | Sensitivity to rates, inflation, VIX, USD |
| `getEarningsPrediction(ticker)` | ML earnings beat/miss prediction |
| `getEstimateRevisions(ticker)` | Analyst EPS revision trends |
| `getCorrelatedStocks(ticker)` | Price correlation analysis with sector peers |
| `getInstitutionalOwnership(ticker)` | Top holders, whale activity, concentration risk |
| `getGeographicRevenue(ticker)` | Revenue by geographic region |
| `getSegmentRevenue(ticker)` | Business segment revenue breakdown |

### Screening & Portfolio (7 tools)

| Tool | Description |
|------|-------------|
| `screenStocks(...)` | Multi-factor screen of 2,260+ stocks |
| `deepValueScreen(sector?, limit?)` | Piotroski ≥ 6 value stocks |
| `compareTickers(tickers)` | 2-5 stocks side-by-side |
| `computeMetric(metric, aggregation)` | Aggregate statistics across top 100 stocks |
| `getPortfolioAnalysis(tickers)` | Multi-holding portfolio analytics |
| `crossReferencePortfolio(tickers)` | Portfolio vs market signal alignment |
| `getStrategyPicks(strategy?)` | Pre-computed strategy picks |

### Market & Macro (13 tools)

| Tool | Description |
|------|-------------|
| `getMarketSignal()` | Current signal with 5-component breakdown |
| `getRegimeAnalysis()` | Macro regime classification |
| `getMacroIndicator(indicator)` | FRED data (CPI, GDP, rates, etc.) |
| `getFearGreedIndex(timeline?)` | Fear & Greed with optional history |
| `getSectorBreakdown(sector?)` | Top stocks by market cap for a sector |
| `getBLSIndicator(series_id)` | BLS economic data (employment, CPI, PPI) |
| `getMacroAttention(weeks?)` | Macro Google Search Volume for stress terms |
| `getRegimeTransitions(days?)` | Historical regime transitions |
| `getSignalHistory(days?)` | Daily signal history + SPY returns |
| `getMarketBreadth(period_type?)` | Advance/decline, new highs/lows |
| `getEarningsCalendar(from?, to?)` | Upcoming earnings reports calendar |
| `searchStocks(query)` | Fuzzy search 2,260+ US equities |
| `getMarketHeatmap()` | Sector performance heatmap with top gainers/losers |

### Alternative Data (9 tools)

| Tool | Description |
|------|-------------|
| `getInsiderActivity(ticker)` | SEC Form 4 insider trades |
| `getCongressionalTrades(...)` | STOCK Act trades |
| `getEarningsSurprises(ticker)` | Historical beats/misses |
| `getAccelerationMatrix(...)` | Revenue & earnings acceleration |
| `getLargeShareholderFilings(ticker)` | 13D/13G activist & ownership filings |
| `getLaborEfficiency(ticker)` | Revenue/employee, SGA/employee, headcount |
| `getETFExposure(ticker)` | Reverse ETF lookup with weights |
| `getClinicalTrials(ticker?, phase?)` | Biotech/pharma trial pipeline |
| `getLobbyingActivity(ticker?, sector?)` | Federal lobbying spend & issues |

### Advanced Analysis (11 tools — Tier 2)

| Tool | Description |
|------|-------------|
| `getNextEarnings(ticker)` | Next earnings date and reporting details |
| `getPeerComparison(ticker)` | Peer group analysis with relative rankings |
| `getValuationHistory(ticker)` | Historical P/E, P/S, EV/EBITDA time series |
| `getRiskMetrics(ticker)` | Beta, max drawdown, Sharpe, Sortino, VaR |
| `getAnnualTrends(ticker)` | Multi-year revenue, income, margins trajectory |
| `getKPIs(ticker)` | Industry-specific KPIs and operational metrics |
| `getAttentionSignals(ticker)` | Wikipedia + Google Trends anomalies |
| `getAcademicFactors(ticker)` | Residual income, accruals quality, Fama-French |
| `getForesightScore(ticker)` | ML composite foresight/trajectory score |
| `getInsiderSignals(ticker)` | Derived insider conviction patterns and clusters |
| `getAIVerdict(ticker)` | AI analyst buy/hold/sell verdict with thesis |

### Business Exclusive (13 tools — Tier 3)

| Tool | Description |
|------|-------------|
| `getGovtContracts(ticker?, agency?)` | Government contract awards (by company or screened) |
| `getVolatilityProfile(ticker)` | Volatility analysis: risk metrics, vs SPY benchmark |
| `getRedditMentions(ticker?)` | Reddit sentiment & mention trends |
| `getMergerDeals(status?, ticker?)` | Active M&A deals with spreads |
| `getBatchEarningsPredictions(tickers)` | ML predictions for multiple tickers |
| `getETFBreakdown(ticker)` | ETF holdings, sector breakdown |
| `getIPOCalendar(range?)` | Upcoming IPOs with pricing details |
| `getAttentionAlerts(days?)` | Unusual attention spikes across universe |
| `getMacroSentiment()` | Full sentiment: AAII, VIX, put/call, ISM |
| `getGovtContractSummary(ticker)` | Aggregated contract exposure: 12-month totals, top agencies |
| `getBatchRiskMetrics(tickers)` | Risk metrics for multiple tickers |
| `getFactorModelScores(model)` | 18 academic factor models with scores |
| `getMarketStreaks(sector?)` | Stocks on quality improvement streaks |

## Resources

| Resource URI | Description | Cache |
|-------------|-------------|-------|
| `finstill://market/signal` | Current market signal | 5 min |
| `finstill://market/regime` | Macro regime | 1 hour |
| `finstill://market/fear-greed` | Fear & Greed Index | 1 hour |
| `finstill://sectors/overview` | Sector aggregates | 1 hour |
| `finstill://company/{ticker}` | Company summary | 24 hours |
| `finstill://meta/tools` | Tool documentation | Static |
| `finstill://meta/coverage` | Covered tickers | 24 hours |

## Prompts

| Prompt | Args | Description |
|--------|------|-------------|
| `analyze-stock` | `{ticker}` | Full stock analysis (15 tools) |
| `compare-stocks` | `{tickers}` | Side-by-side comparison |
| `screen-stocks` | `{criteria}` | NL criteria → stock screen |
| `macro-outlook` | — | Macro environment summary (10 tools) |
| `sector-rotation` | — | Sector rotation analysis |
| `earnings-preview` | `{ticker}` | Pre-earnings analysis (10 tools) |
| `portfolio-health-check` | `{tickers}` | Portfolio health: quality, risk, concentration |
| `alternative-data-scan` | `{ticker}` | Non-traditional data deep dive |
| `market-dashboard` | — | Comprehensive market overview (13 tools) |
| `deep-value-hunt` | `{sector?}` | Deep value stock discovery |

## Programmatic Usage

```typescript
import { createServer, connectStdio } from '@fffinstill/mcp-server';

const server = createServer({
  apiUrl: 'https://fffinstill.com',
  apiKey: process.env.FINSTILL_API_KEY!,
});

await connectStdio(server);
```

## MCP Compliance

This server implements the full MCP specification:

- **Tool annotations**: All 69 tools declare `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: true`, and human-readable `title` fields
- **Resource metadata**: All resources include `title`, `mimeType`, `description`, and audience/priority annotations
- **Capabilities**: Explicitly declares `tools`, `resources`, and `prompts` with `listChanged: false`
- **Server instructions**: Provides server-level instructions for LLM context

## Rate Limits

Rate limits depend on your subscription tier:

| Plan | Requests/min | Monthly cap |
|------|-------------|-------------|
| Founding | 20 | 1,000 |
| Pro | 20 | 1,000 |
| Business | 60 | Unlimited |

## License

MIT