# SEC EDGAR Company Filings & XBRL Financials MCP Server (`mutualistic_housing/sec-edgar-filings-mcp`) Actor

Query SEC EDGAR 10-K, 10-Q, 8-K filings, full-text EFTS search, corporate profiles, and standardized US-GAAP XBRL financial facts with YoY growth via Batch JSON API or Standby MCP Server.

- **URL**: https://apify.com/mutualistic_housing/sec-edgar-filings-mcp.md
- **Developed by:** [Mutualistic Labs](https://apify.com/mutualistic_housing) (community)
- **Categories:** AI, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## MCP Server for AI Agents: SEC EDGAR Filings & XBRL Financials

An always-on **Model Context Protocol (MCP) server** and batch Actor for **SEC EDGAR**: recent **company filings** (10-K, 10-Q, 8-K,
Form 4, 13F), EDGAR **full-text search**, **company profiles** and exact **XBRL financial facts** with **year-over-year growth**. Built
for AI agents (Claude Desktop, Cursor, Windsurf, OpenAI Agents, LangChain), equity research, compliance monitoring, event-driven alerts
and financial data pipelines.

No proxies, no browser, no logins, no API keys: only the official, unauthenticated SEC JSON APIs are called (`data.sec.gov`,
`efts.sec.gov`, `www.sec.gov`) with a compliant, identifying User-Agent.

### Features

- Four modes: `company_filings`, `search_filings`, `company_profile`, `financial_facts`.
- Filings of one or many companies (tickers or CIKs, up to 10) with form, date range and keyword filters; every filing carries a direct
  `https://www.sec.gov/Archives/...` document link and the filing index link.
- Full-text search across all EDGAR filings (`search_filings`), optionally restricted to given companies (CIKs; the bare default `["AAPL"]`
  prefill is treated as "not set", so use `0000320193` or add another company to force an Apple-only search), forms and dates.
- Company profiles: CIK, name, tickers, exchanges, SIC, EIN, state of incorporation, fiscal year end, business address, latest 10-K and
  10-Q dates and links.
- XBRL financial facts per company and concept with exact values and `yoy_change_pct`.
- Deterministic de-duplication (`uid`), hard `max_items` and `max_total_charge_usd` caps.

### What you get

| `record_type` | Mode | What it is |
|---|---|---|
| `filing` | `company_filings`, `search_filings` | One SEC filing (form, dates, items, primary document, XBRL flags, links) |
| `company_profile` | `company_profile` | One company (identity, tickers, SIC, address, latest 10-K and 10-Q) |
| `financial_fact` | `financial_facts` | One XBRL fact (concept, unit, value, period, filing, YoY change) |

### Endpoints

- `GET /` and `GET /health`: readiness probe, returns `{"status":"ok","actor":"sec-edgar-filings-mcp",...}`.
- `POST /mcp`: MCP JSON-RPC 2.0 (`initialize`, `ping`, `tools/list`, `tools/call`).

Standby URL: `https://mutualistic-housing--sec-edgar-filings-mcp.apify.actor/mcp` (authenticate with your Apify API token).

### Input

| Field | Type | Default |
|---|---|---|
| `mode` | `company_filings`, `search_filings`, `company_profile`, `financial_facts` | `company_filings` |
| `companies` | string\[] of tickers or CIKs, 1 to 10 | none (prefill AAPL; falls back to AAPL). In `search_filings` they restrict the search to those CIKs, but the bare default `["AAPL"]` counts as "not set" (no restriction); use the CIK form `0000320193` or add another company to restrict to Apple |
| `forms` | string\[] of form types such as `10-K`, up to 20 | all forms |
| `query` | string, max 300 chars (required for `search_filings`; keyword filter in `company_filings`) | none |
| `concepts` | string\[] of preset keys or XBRL tags, 1 to 10 (mode `financial_facts`) | `["NetIncomeLoss"]` |
| `taxonomy` | `us-gaap`, `dei`, `ifrs-full` (non-preset concepts) | `us-gaap` |
| `start_date`, `end_date` | `YYYY-MM-DD`; filing date for filings, period end date for facts | none |
| `max_items` | integer 1 to 500 | `25` |
| `max_total_charge_usd` | number or null | no cap |

An empty `{}` input runs: the 25 latest filings of Apple (`AAPL`). camelCase aliases (`startDate`, `endDate`, `maxItems`,
`maxTotalChargeUsd`) are accepted. Invalid input is rejected with `INVALID_INPUT_ZERO_CHARGE` before any network call or charge.

#### Batch input examples

Latest annual and quarterly reports of three companies:

```json
{"mode": "company_filings", "companies": ["AAPL", "MSFT", "NVDA"], "forms": ["10-K", "10-Q"], "max_items": 30}
```

Full-text search for 10-K filings that mention a topic:

```json
{"mode": "search_filings", "query": "artificial intelligence", "forms": ["10-K"], "start_date": "2025-01-01", "end_date": "2025-12-31"}
```

Company profiles:

```json
{"mode": "company_profile", "companies": ["AAPL", "BRK-B", "320193"]}
```

Revenue and net income with year-over-year change from annual reports:

```json
{"mode": "financial_facts", "companies": ["AAPL"], "concepts": ["Revenues", "NetIncomeLoss"], "forms": ["10-K"], "max_items": 20}
```

### Preset companies and concepts

Companies (tickers are resolved without a lookup request; any other ticker or CIK works too): `AAPL`, `MSFT`, `NVDA`, `GOOGL`, `AMZN`,
`META`, `TSLA`, `BRK-B`, `JPM`, `LLY`.

Concepts: `Revenues` (falls back to `RevenueFromContractWithCustomerExcludingAssessedTax` and `SalesRevenueNet`), `NetIncomeLoss`,
`OperatingIncomeLoss`, `Assets`, `Liabilities`, `StockholdersEquity`, `CashAndCashEquivalentsAtCarryingValue`,
`EarningsPerShareDiluted`, `CommonStockSharesOutstanding` (`dei:EntityCommonStockSharesOutstanding` or
`us-gaap:CommonStockSharesOutstanding`). Any other XBRL tag works with `taxonomy`.

### MCP tools

```json
{
  "mcpServers": {
    "sec-edgar": {
      "url": "https://mutualistic-housing--sec-edgar-filings-mcp.apify.actor/mcp",
      "headers": { "Authorization": "Bearer <APIFY_TOKEN>" }
    }
  }
}
```

- **`get_company_filings`**: `companies`, `forms`, `query`, `start_date`, `end_date`, `max_items` (default 10).
- **`search_sec_filings`**: `query` (required), `forms`, `start_date`, `end_date`, `max_items`.
- **`get_company_profiles`**: `companies`.
- **`get_financial_facts`**: `companies`, `concepts`, `taxonomy`, `forms`, `start_date`, `end_date`, `max_items`.
- **`list_preset_companies`**: no arguments; lists the preset companies and concepts (free).

Example calls:

```bash
curl -X POST "https://mutualistic-housing--sec-edgar-filings-mcp.apify.actor/mcp" \
  -H "Authorization: Bearer <APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_company_filings","arguments":{"companies":["AAPL"],"forms":["10-K"],"max_items":5}}}'
```

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_sec_filings","arguments":{"query":"artificial intelligence","forms":["10-K"],"max_items":10}}}
```

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_company_profiles","arguments":{"companies":["AAPL","NVDA"]}}}
```

```json
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_financial_facts","arguments":{"companies":["AAPL"],"concepts":["NetIncomeLoss"],"forms":["10-K"],"max_items":5}}}
```

```json
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"list_preset_companies","arguments":{}}}
```

### Output fields

Filing records:

| Field | Meaning |
|---|---|
| `record_type`, `uid` | Record kind; deterministic SHA-256 identifier |
| `cik`, `company_name`, `tickers` | 10-digit CIK, company name and ticker symbols |
| `accession_number`, `form` | SEC accession number and form type |
| `filing_date`, `report_date`, `acceptance_datetime` | Filing date, period or event date, SEC acceptance timestamp |
| `act`, `file_number`, `film_number` | Securities act, SEC file number and film number |
| `items` | 8-K item numbers such as `2.02`, `9.01` |
| `description`, `primary_document` | Document description and primary document file name |
| `size_bytes`, `is_xbrl`, `is_inline_xbrl` | Filing size and XBRL flags (submissions data only) |
| `filing_url`, `index_url` | Direct document link (or the index page when the primary document is not a plain file) and the filing index page |
| `source` | Upstream SEC API |

The filing `uid` is derived from the CIK, accession number and primary document.

Company profile records:

| Field | Meaning |
|---|---|
| `record_type`, `uid` | Record kind; deterministic SHA-256 identifier |
| `cik`, `company_name`, `entity_type` | Identity |
| `sic`, `sic_description` | Standard Industrial Classification |
| `tickers`, `exchanges`, `ein` | Tickers, listing exchanges (parallel to tickers) and employer identification number |
| `state_of_incorporation`, `fiscal_year_end` | State or country of incorporation and fiscal year end (`MMDD`) |
| `business_city`, `business_state` | Business address |
| `recent_filings_count` | Number of filings in the recent filings list |
| `latest_10k_date`, `latest_10k_url`, `latest_10q_date`, `latest_10q_url` | Filing date and link of the latest 10-K and 10-Q |
| `sec_browse_url`, `source` | EDGAR company page; upstream SEC API |

Financial fact records:

| Field | Meaning |
|---|---|
| `record_type`, `uid` | Record kind; deterministic SHA-256 identifier |
| `cik`, `company_name` | Company |
| `taxonomy`, `concept`, `label` | XBRL taxonomy, tag and human-readable label |
| `unit`, `value` | `USD`, `USD/shares` or `shares`; exact reported value (integers unchanged, decimals rounded half-up to 4 places) |
| `start_date`, `end_date` | Period; instant facts (balance sheet) have no `start_date` |
| `fiscal_year`, `fiscal_period` | Fiscal year and period of the reporting filing, not of the fact period |
| `form`, `filed_date`, `accession_number`, `frame` | Reporting filing and XBRL frame |
| `yoy_change_pct` | Year-over-year change in percent; see below |
| `source` | Upstream SEC API |

The fact `uid` is derived from the CIK, taxonomy, concept, unit, accession number, `start_date`, `end_date`, `fiscal_period` and `frame`. It includes `start_date`, so a 3-month and a 9-month fact of the same filing that share the same `end_date` stay distinct records.

Example financial fact (shortened):

```json
{
  "record_type": "financial_fact", "cik": "0000320193", "company_name": "Apple Inc.", "taxonomy": "us-gaap",
  "concept": "NetIncomeLoss", "unit": "USD", "value": 93736000000, "start_date": "2023-10-01", "end_date": "2024-09-28",
  "fiscal_year": 2024, "fiscal_period": "FY", "form": "10-K", "filed_date": "2024-11-01", "yoy_change_pct": -3.36,
  "uid": "<sha256>"
}
```

#### Year-over-year rule

`yoy_change_pct` is matched by period dates, not by `fiscal_year` (the fiscal year of a filing also covers the comparative periods
it repeats). For each fact the prior-year fact has the same unit, the same kind (instant or duration), a period end 358 to 372 days
earlier and, for durations, a length within 7 days. If several prior facts match, the most recently filed one is used. The result is
`(value - prior) / |prior| * 100`, rounded half-up to 2 decimals. It is `null` when no comparable period exists or when the prior value
is zero or negative.

### SEC fair access

The SEC asks automated clients to identify themselves and stay below 10 requests per second. This Actor sends the User-Agent
`MutualisticLabs-SecEdgarMCP/0.1 (support@mutualisticlabs.com)`, keeps its own
requests below that rate with a process-wide limiter shared by all clients and concurrent MCP calls (at most 8 requests per second, one
request start every 0.125 s), backs off on `429` and 5xx responses and honours
`Retry-After`. Data comes straight from the SEC and is not investment advice.

### Security and limits

- **Allowlisted hosts only**: outbound requests go exclusively to `data.sec.gov`, `efts.sec.gov` and `www.sec.gov` over https. Redirects
  to any other host, non-https redirects, credentials in URLs and non-443 ports are rejected.
- **SSRF protections**: DNS results (and the connected peer address, checked before any body is read) that are loopback, private,
  link-local, CGNAT, NAT64, 6to4, Teredo, multicast or unspecified are refused. Resolved IP addresses never appear in error messages.
- **Bounds**: at most 500 items per run, 10 companies and 10 concepts per call, a 120 s global batch deadline, a 45 s deadline per
  MCP tool call, a 15 s per-request timeout (connect, TLS, headers and body) and a 4 MiB response size cap.
- **MCP server**: request bodies above 64 KiB return `413`, `POST /mcp` requires `Content-Type: application/json` (`415` otherwise)
  and at most 8 concurrent tool calls run (`503` when busy).
- Unknown tickers, CIKs or concepts return an error entry for that company or concept; per-company failures never abort other
  companies.

### Pricing

Pay per event: **$0.001 per result-item** (`result-item`: one de-duplicated filing, company profile or financial fact, as a dataset
item or an MCP tool result row); the `actor-start` event is free and `list_preset_companies` is free. `max_items` and
`max_total_charge_usd` are hard caps enforced in code, so a run never charges more than you configure. Invalid input and empty results
are never charged.

### Related MCP Servers by Mutualistic Labs

| Actor | Covers | Store | Standby MCP URL |
|---|---|---|---|
| Multi-ATS Career Jobs Search MCP | Greenhouse, Lever, Ashby, SmartRecruiters, Workable | https://apify.com/mutualistic_housing/multi-ats-career-jobs-mcp | https://mutualistic-housing--multi-ats-career-jobs-mcp.apify.actor/mcp |
| Google Ads Transparency & Ad Spy MCP | SearchCreatives, SearchSuggestions, `content.js` ad-copy & video metadata | https://apify.com/mutualistic_housing/google-ads-transparency-mcp | https://mutualistic-housing--google-ads-transparency-mcp.apify.actor/mcp |
| Multi-Engine Keyword & Autocomplete MCP | Google, YouTube, Amazon, Bing, DuckDuckGo, Brave + `google:suggestrelevance` & search intent | https://apify.com/mutualistic_housing/keyword-autocomplete-mcp | https://mutualistic-housing--keyword-autocomplete-mcp.apify.actor/mcp |
| Discourse Forum Search & Threads MCP | community.openai.com, discuss.huggingface.co, meta.discourse.org + any public Discourse | https://apify.com/mutualistic_housing/discourse-forum-mcp | https://mutualistic-housing--discourse-forum-mcp.apify.actor/mcp |
| Google Trends Realtime & Entities MCP | i0OFE realtime trends, trending/rss news, Knowledge Graph autocomplete entities | https://apify.com/mutualistic_housing/google-trends-realtime-mcp | https://mutualistic-housing--google-trends-realtime-mcp.apify.actor/mcp |
| Substack Newsletter, Posts & Podcast MCP | Publication search, archives & within-newsletter search, full post Markdown, podcast audio URLs | https://apify.com/mutualistic_housing/substack-newsletter-mcp | https://mutualistic-housing--substack-newsletter-mcp.apify.actor/mcp |
| Shopify Store Catalog & Search MCP | Products, variants/SKU/price/availability, collections, predictive search on any public Shopify store | https://apify.com/mutualistic_housing/shopify-store-catalog-mcp | https://mutualistic-housing--shopify-store-catalog-mcp.apify.actor/mcp |
| Bluesky Social Search & Threads MCP | Post search, author feeds, profiles & follower ratios, full reply threads via public AT Protocol AppView | https://apify.com/mutualistic_housing/bluesky-social-search-mcp | https://mutualistic-housing--bluesky-social-search-mcp.apify.actor/mcp |
| SEC EDGAR Filings & XBRL Financials MCP | Company filings (10-K, 10-Q, 8-K, Form 4, 13F), full-text search, company profiles, XBRL financial facts with YoY growth | https://apify.com/mutualistic_housing/sec-edgar-filings-mcp | https://mutualistic-housing--sec-edgar-filings-mcp.apify.actor/mcp |

# Actor input Schema

## `mode` (type: `string`):

company_filings = recent filings of each company; search_filings = EDGAR full-text search (needs query); company_profile = company profiles with latest 10-K and 10-Q; financial_facts = XBRL facts per company and concept with YoY change.

## `companies` (type: `array`):

Tickers (e.g. AAPL, BRK-B) or CIK numbers (e.g. 320193 or CIK0000320193), 1 to 10. Presets: AAPL, MSFT, NVDA, GOOGL, AMZN, META, TSLA, BRK-B, JPM, LLY. Empty means AAPL. In mode search_filings the companies restrict the search to these CIKs, except that the bare default \["AAPL"] (the Console prefill) is treated as not set and does not restrict the search; to force an Apple-only search use the CIK form 0000320193 or add another company.

## `forms` (type: `array`):

Keep only these SEC form types, e.g. 10-K, 10-Q, 8-K, 4, 13F-HR (up to 20). Empty means all forms.

## `query` (type: `string`):

Required for mode search_filings (up to 300 characters): EDGAR full-text search phrase. In mode company_filings it is an optional keyword filter.

## `concepts` (type: `array`):

Mode financial_facts: concept names, 1 to 10. Presets: Revenues, NetIncomeLoss, OperatingIncomeLoss, Assets, Liabilities, StockholdersEquity, CashAndCashEquivalentsAtCarryingValue, EarningsPerShareDiluted, CommonStockSharesOutstanding. Any other XBRL tag works with the chosen taxonomy. Empty means NetIncomeLoss.

## `taxonomy` (type: `string`):

Mode financial_facts: XBRL taxonomy for concepts that are not presets.

## `start_date` (type: `string`):

Keep results from this date on (YYYY-MM-DD): filing date for filings, period end date for financial facts.

## `end_date` (type: `string`):

Keep results up to this date (YYYY-MM-DD): filing date for filings, period end date for financial facts.

## `max_items` (type: `integer`):

Maximum number of result items to return (and be charged for), 1 to 500.

## `max_total_charge_usd` (type: `number`):

Hard spending cap for this run; results are truncated so the charge never exceeds it.

## Actor input object example

```json
{
  "mode": "company_filings",
  "companies": [
    "AAPL"
  ],
  "concepts": [
    "NetIncomeLoss"
  ],
  "taxonomy": "us-gaap",
  "max_items": 25
}
```

# Actor output Schema

## `items` (type: `string`):

Dataset items: filing, company profile and financial fact records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "companies": [
        "AAPL"
    ],
    "concepts": [
        "NetIncomeLoss"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("mutualistic_housing/sec-edgar-filings-mcp").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "companies": ["AAPL"],
    "concepts": ["NetIncomeLoss"],
}

# Run the Actor and wait for it to finish
run = client.actor("mutualistic_housing/sec-edgar-filings-mcp").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "companies": [
    "AAPL"
  ],
  "concepts": [
    "NetIncomeLoss"
  ]
}' |
apify call mutualistic_housing/sec-edgar-filings-mcp --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,mutualistic_housing/sec-edgar-filings-mcp"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/uo78HidhYIJvhH9ts/builds/LJnhFRl2fivvXQ7Y1/openapi.json