@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 13 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

Sign up at fffinstill.com and generate an API key at 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):

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

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