📊 S&P 500 & Nasdaq-100 Free Cash Flow BI Analyzer (MCP & API)

Give your LLM agents, financial research workflows, and investment pipelines verified, context-ready cash flow intelligence directly from official SEC EDGAR 10-K / 20-F XBRL filings. In one call, retrieve 5-year historical Operating Cash Flow (OCF), CapEx, Headline Free Cash Flow (FCF), SBC-Adjusted True FCF, FCF Margin %, FCF Conversion Rate, and automated Business Intelligence (BI) diagnostic flags.

Designed specifically for AI agents (via Model Context Protocol - MCP) and quantitative/financial applications (via REST API), this Actor eliminates LLM arithmetic hallucinations and context-window bloat by returning pre-cleaned, pre-aggregated institutional BI metrics instead of raw multi-megabyte SEC filings.

---

Main features

• ⚡ Sub-10ms response times for 516 pre-cached S&P 500 & Nasdaq-100 (QQQ) constituents backed by an embedded 1.08 MB SQLite analytical engine.
• 🔄 Hybrid Read-Through Lazy Cache: Instant local lookup for S&P 500 / Nasdaq-100 giants, with automatic on-the-fly SEC EDGAR XBRL extraction and 7-day caching for 5,000+ other US public equities.
• 💎 SBC-Adjusted "True FCF": Automatically deducts Stock-Based Compensation (SBC) from Headline FCF (OCF - CapEx - SBC) to expose real cash generation after employee equity dilution.
• 🧠 Automated BIE Diagnostic Flags: Built-in Business Intelligence rules automatically flag High SBC Dilution (>25% of FCF), Aggressive CapEx Expansion (>+35% YoY AI/infrastructure buildout), and Working Capital / Earnings Quality Drag.
• 🏷️ Index Membership & Period Metadata: Every record is tagged with is_sp500 (bool), is_qqq_100 (bool), fiscal_year (int), and quarter (enum: 1, 2, 3, 4).
• 🔍 Cross-Company Cash Cow Screener & Peer Benchmarking: Screen all 516 index constituents by minimum FCF margin or rank peers side-by-side in milliseconds.
• 🔌 Native MCP & REST API Support: Run as a local stdio MCP server (Claude Desktop, Cursor, Windsurf), an HTTP Standby API server, or a standard Apify Actor.
• 🛡️ 100% Official SEC EDGAR Data: Zero third-party API keys required and zero anti-scraping risk. Contains both us-gaap and ifrs-full XBRL taxonomy parsers.

---

Example

1. Single Company 5-Year Deep Dive (get_company_fcf_analysis)

For a ticker query like ARM or NVDA, the Actor returns a structured BI summary along with a 5-year annual historical series:

{
  "ticker": "ARM",
  "company_name": "Arm Holdings plc",
  "sector": "Information Technology",
  "is_sp500": false,
  "is_qqq_100": true,
  "latest_fiscal_year": 2026,
  "quarter": 1,
  "headline_fcf_millions": 979.0,
  "sbc_adjusted_true_fcf_millions": -73.0,
  "fcf_margin_pct": 19.9,
  "true_fcf_margin_pct": -1.48,
  "fcf_conversion_pct": 108.3,
  "fcf_yoy_growth_pct": 450.0,
  "bie_diagnostic_flags": [
    "High SBC Dilution: Stock-Based Comp consumes 107.5% of headline FCF.",
    "Aggressive CapEx Expansion: CapEx jumped +148.9% YoY (e.g., AI/Infra buildout)."
  ],
  "historical_5yr_annual": [
    {
      "ticker": "ARM",
      "cik": "0001973239",
      "company_name": "Arm Holdings plc",
      "sector": "Information Technology",
      "is_sp500": false,
      "is_qqq_100": true,
      "fiscal_year": 2026,
      "quarter": 1,
      "period_end": "2026-03-31",
      "ocf_millions": 1524.0,
      "capex_millions": 545.0,
      "fcf_millions": 979.0,
      "sbc_millions": 1052.0,
      "true_fcf_millions": -73.0,
      "revenue_millions": 4920.0,
      "net_income_millions": 904.0,
      "fcf_margin_pct": 19.9,
      "true_fcf_margin_pct": -1.48,
      "fcf_conversion_pct": 108.3,
      "fcf_yoy_growth_pct": 450.0,
      "updated_at": 1792988675
    }
  ]
}

2. Side-by-Side Peer Comparison (compare_peers_fcf)

Compare multiple competitors or index heavyweights (["NVDA", "MSFT", "AAPL", "AMZN", "META", "GOOGL"]) in a single call:

{
  "peer_comparison": [
    {
      "ticker": "NVDA",
      "company_name": "NVIDIA CORP",
      "is_sp500": true,
      "is_qqq_100": true,
      "fy": 2026,
      "quarter": 1,
      "headline_fcf_M": 96676.0,
      "sbc_adj_true_fcf_M": 90290.0,
      "fcf_margin_pct": 44.77,
      "true_fcf_margin_pct": 41.81,
      "fcf_yoy_growth_pct": 58.87,
      "flags": [
        "Aggressive CapEx Expansion: CapEx jumped +86.7% YoY (e.g., AI/Infra buildout)."
      ]
    },
    {
      "ticker": "AMZN",
      "company_name": "AMAZON COM INC",
      "is_sp500": true,
      "is_qqq_100": true,
      "fy": 2025,
      "quarter": 4,
      "headline_fcf_M": 7695.0,
      "sbc_adj_true_fcf_M": -11772.0,
      "fcf_margin_pct": 1.07,
      "true_fcf_margin_pct": -1.64,
      "fcf_yoy_growth_pct": -76.6,
      "flags": [
        "High SBC Dilution: Stock-Based Comp consumes 253.0% of headline FCF.",
        "Working Capital / CapEx Drag: FCF is only 9.91% of Net Income.",
        "Aggressive CapEx Expansion: CapEx jumped +58.8% YoY (e.g., AI/Infra buildout)."
      ]
    }
  ]
}

3. Dataset Ticker Directory (list)

Retrieve all cached S&P 500 and Nasdaq-100 constituents and their index membership flags:

{
  "total_count": 516,
  "tickers": [
    {
      "ticker": "AAPL",
      "company_name": "Apple Inc.",
      "sector": "Information Technology",
      "is_sp500": true,
      "is_qqq_100": true,
      "fiscal_year": 2025,
      "quarter": 3,
      "period_end": "2025-09-27"
    },
    {
      "ticker": "ARM",
      "company_name": "Arm Holdings plc",
      "sector": "Information Technology",
      "is_sp500": false,
      "is_qqq_100": true,
      "fiscal_year": 2026,
      "quarter": 1,
      "period_end": "2026-03-31"
    }
  ]
}

---

⚙️ Usage

The S&P 500 & Nasdaq-100 FCF Analyzer can be used in three ways: as a native MCP server, in HTTP Standby / REST API mode, or as a standard Apify Actor.

1. Normal Actor run

You can run the Actor via the Apify API, schedules, integrations, or manually in the Apify Console by passing an input JSON object:

{
  "action": "get_company_fcf_analysis",
  "ticker": "NVDA"
}

Supported action values:

• get_company_fcf_analysis: Returns 5-year FCF metrics and diagnostic flags for ticker.
• compare_peers_fcf: Side-by-side comparison for an array of tickers.
• screen_sp500_cash_cows: Screens the 516 cached index constituents by min_fcf_margin_pct, sector, and sort_by.
• list: Lists all tickers in the dataset with is_sp500, is_qqq_100, fiscal_year, and quarter.

2. Standby web server / HTTP REST API

When running in Standby mode, you can query clean REST endpoints directly via GET requests for sub-second responses:

# Single company 5-year FCF analysis
curl "https://chlorella2026--sp500-ndx100-fcf-mcp.apify.actor/api/fcf?token=<APIFY_API_TOKEN>&ticker=NVDA"

# Multi-company peer comparison
curl "https://chlorella2026--sp500-ndx100-fcf-mcp.apify.actor/api/compare?token=<APIFY_API_TOKEN>&tickers=NVDA,MSFT,AAPL,AMZN,META,GOOGL"

# Cash cow screener (FCF Margin >= 25%, ranked by SBC-adjusted True FCF)
curl "https://chlorella2026--sp500-ndx100-fcf-mcp.apify.actor/api/screen?token=<APIFY_API_TOKEN>&min_fcf_margin_pct=25&sort_by=true_fcf_millions"

# List all cached S&P 500 & Nasdaq-100 tickers
curl "https://chlorella2026--sp500-ndx100-fcf-mcp.apify.actor/api/list?token=<APIFY_API_TOKEN>"

Query parameters

Endpoint	Parameter	Type	Default	Description
/api/fcf	ticker	string	"NVDA"	Stock ticker symbol (e.g., AAPL, MSFT, COST).
/api/compare	tickers	string	"NVDA,MSFT,AAPL"	Comma-separated list of stock tickers.
/api/screen	min_fcf_margin_pct	number	15.0	Minimum Headline FCF Margin % filter.
/api/screen	sort_by	string	"true_fcf_millions"	Sort column (true_fcf_millions, fcf_millions, fcf_margin_pct, true_fcf_margin_pct, fcf_yoy_growth_pct).
/api/list	cached_only	boolean	true	Return cached dataset tickers (true) or full index universe (false).
/api/list	sp500_only	boolean	false	Filter to S&P 500 constituents only.
/api/list	qqq100_only	boolean	false	Filter to Nasdaq-100 (QQQ) constituents only.

---

🔌 Integration with LLMs (MCP)

This Actor is designed for seamless integration with LLM applications, Claude Desktop, Cursor, Windsurf, OpenAI Assistants, and custom RAG/Agent pipelines via the Apify MCP Server.

Connect via Apify MCP Server (Claude Desktop / Cursor)

Add the following configuration to your claude_desktop_config.json or .cursor/mcp.json using your APIFY_API_TOKEN:

{
  "mcpServers": {
    "apify-sp500-fcf": {
      "command": "npx",
      "args": [
        "-y",
        "@apify/actors-mcp-server",
        "--actors",
        "chlorella2026/sp500-ndx100-fcf-mcp"
      ],
      "env": {
        "APIFY_TOKEN": "<YOUR_APIFY_API_TOKEN>"
      }
    }
  }
}

Once connected, your AI assistant can invoke 4 core BI capabilities:

1. list — Discover all 516 S&P 500 and Nasdaq-100 tickers in the dataset along with is_sp500 and is_qqq_100 flags.
2. get_company_fcf_analysis — Retrieve 5-year cash flow metrics and BIE diagnostic flags for a company.
3. compare_peers_fcf — Run side-by-side peer cash flow benchmarking.
4. screen_sp500_cash_cows — Screen the index for high-margin cash generators.

---

📐 BI Methodology & Metrics Definition

Generic financial scrapers only report raw accounting numbers. This engine applies institutional Business Intelligence transformations to surface true cash profitability:

Field	Formula / Source	Why it matters for LLMs & Analysts
ocf_millions	SEC 10-K/20-F Operating Cash Flow	Cash generated from core business operations ($ Millions).
capex_millions	Payments to Acquire PP&E / Productive Assets	Capital expenditures required to maintain and grow infrastructure ($ Millions).
fcf_millions	OCF - CapEx	Standard Headline Free Cash Flow ($ Millions).
sbc_millions	Share-Based Compensation Expense	Non-cash employee equity compensation ($ Millions).
true_fcf_millions	FCF - SBC	SBC-Adjusted True FCF: Treats recurring employee stock grants as a real economic cash cost.
fcf_margin_pct	(FCF / Revenue) * 100	Percentage of every revenue dollar converted into Headline FCF.
true_fcf_margin_pct	(True FCF / Revenue) * 100	Percentage of revenue converted into FCF after deducting SBC dilution.
fcf_conversion_pct	(FCF / Net Income) * 100	Earnings quality indicator (>100% signals strong cash backing of GAAP earnings).
quarter	enum(1, 2, 3, 4)	Calendar quarter corresponding to the fiscal year-end period (period_end).

---

⏳ Performance optimization & Architecture

[ AI Agent / API Client Request ]
               │
    ┌──────────┴──────────┐
(S&P 500 / QQQ 100)   (Other US Tickers)
    │                     │
Local SQLite Engine   SEC EDGAR XBRL API (Lazy Mode)
(516 companies, 1MB)      │
    │                 Parse 10-K + Compute BI Ratios
    ▼                     │
 < 5 ms Response      Write-Through to SQLite Cache (7-Day TTL)

Benchmark

Query Type	Data Source	Average Latency	Compute Memory
list (516 companies)	Embedded SQLite (sp500_fcf.db)	~4 ms	128 MB
screen_sp500_cash_cows	Embedded SQLite (sp500_fcf.db)	~6 ms	128 MB
get_company_fcf_analysis (Cached S&P 500 / QQQ)	Embedded SQLite (sp500_fcf.db)	~3 ms	128 MB
get_company_fcf_analysis (Uncached Small-Cap)	Live SEC EDGAR API + Write Cache	~450 ms	256 MB

---

💰 Pricing

When deployed on Apify Store using Pay-Per-Event (PPE) pricing, users pay a predictable micro-fee per BI query rather than paying for idle container compute units:

Event	What it covers	When it is charged
fcf_bi_query	Executing one BI tool action (get_company_fcf_analysis, compare_peers_fcf, screen_sp500_cash_cows, or list).	Once per successful query execution. Failed queries are not charged.
Actor start	Starting up the Actor container for a single run.	On normal Actor runs only. Standby HTTP / MCP requests are not charged for container startup.

---

ⓘ Limitations and feedback

• Coverage: Pre-cached dataset covers 516 out of 518 unique constituents across the S&P 500 (503 tickers) and Nasdaq-100 (102 tickers). Two newly spun-off/registered entities (HONA and SPCX) do not yet have full-year 10-K filings in SEC EDGAR.
• Financial Sector Nuance: For commercial banks and insurance companies (e.g., JPM, BAC), GAAP Operating Cash Flow includes changes in trading assets and loan originations, so FCF Conversion vs. Net Income should be interpreted alongside sector peers.
• Feedback & Feature Requests: If you need additional XBRL metrics, quarterly (10-Q) breakdowns, or sector ratios, please submit an issue on the Actor's page in Apify Console.