@fffinstill/mcp-server

MCP server for fffinstill — 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 18 Business-exclusive tools
7 resources — Market signal, macro regime, Fear & Greed, sector overview, company summaries
10 prompts — Pre-built workflows for stock analysis, comparison, screening, macro outlook, portfolio health, alternative data, market dashboard, deep value

Quick Start

1. Get an API Key

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

{
  "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:

{
  "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:

{
  "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

# 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 (8 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

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 (18 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
`getSignalHistory(days?)`	Daily signal history + SPY returns
`getMarketBreadth(period_type?)`	Advance/decline, new highs/lows
`getEarningsCalendar(days?)`	Upcoming earnings reports calendar
`getBatchEarningsPredictions(tickers)`	ML predictions for multiple tickers
`getETFBreakdown(ticker)`	ETF holdings, sector breakdown
`getIPOCalendar(days?, status?)`	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
`searchStocks(query, limit?)`	Search stocks by name or ticker
`getMarketHeatmap()`	Sector performance heatmap with top gainers/losers
`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

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

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

await connectStdio(server);

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

fffinstill

@fffinstill/mcp-server

Features

Quick Start

1. Get an API Key

2. Configure Your AI Client

Claude Desktop

Cursor

VS Code

3. Use It

CLI Usage

Tools Reference

Stock Analysis (16 tools)

Screening & Portfolio (7 tools)

Market & Macro (8 tools)

Alternative Data (9 tools)

Advanced Analysis (11 tools — Tier 2)

Business Exclusive (18 tools — Tier 3)

Resources

Prompts

Programmatic Usage

Rate Limits

License

Resources

Latest Blog Posts

MCP directory API