SEC-MCP

MCP server for analyzing SEC filings (10-K, 10-Q, 8-K) with industry-aware financial extraction and BERT-based NLP.

Features

• Company Search — Look up companies by ticker or name via SEC EDGAR
• Standardized Financials — Industry-aware XBRL extraction with ~250 concept mappings across 5 industry classes (standard, bank, insurance, REIT, utility)
• Validation — Automatic sanity checks (revenue ≥ net income, accounting equation, segment vs total detection)
• Filing Access — Fetch filing text and specific sections (Risk Factors, MD&A, etc.)
• Sentiment Analysis — FinBERT financial sentiment (positive/negative/neutral)
• Summarization — BART-based hierarchical summarization for long filing sections
• Entity Extraction — NER for companies, people, locations + regex for monetary values, dates, percentages

Setup

# Clone
git clone https://github.com/YOUR_USERNAME/SEC-MCP.git
cd SEC-MCP

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install
pip install -e ".[dev]"

# Configure EDGAR identity (required by SEC)
cp .env.example .env
# Edit .env and set EDGAR_IDENTITY="Your Name your@email.com"

Available Tools

Base / Discovery

Tool	Description
search_company	Search by ticker/name → CIK, ticker, SIC code, industry
get_filing_list	List filings, filter by form type (10-K, 10-Q, 8-K)

Financials (standardized, industry-aware, validated)

Tool	Description
get_financials	Full standardized extraction: metrics, ratios, validation, opt. statements
get_financials_batch	Same as above for N tickers in parallel
get_income_statement	Just the income statement rows
get_balance_sheet	Just the balance sheet rows
get_cash_flow	Just the cash flow rows
get_financial_ratios	Just computed ratios (margins, ROA, ROE, leverage, etc.)
compare_companies	Side-by-side metrics + ratios for multiple tickers

Filing Text

Tool	Description
get_filing_text	Full filing or specific section text (supports aliases like 'risk factors')

NLP Analysis

Tool	Description
analyze_sentiment	FinBERT sentiment on text or filing section
summarize_filing	Hierarchical BART summarization
extract_entities	NER (ORG, PER, LOC, MONEY, DATE, PERCENT)
analyze_filing	Combined sentiment + summary + entities in one call

How financials extraction works

Industry detection

The SIC code is used to classify a company into one of 5 industry classes:

Class	SIC Range	Revenue Strategy
standard	Everything else	First match: Revenues, RevenueFromContractWithCustomer, SalesRevenueNet, …
bank	6020–6299	Try total (Revenues, NetRevenues), then aggregate NII + non-interest + trading + fees
insurance	6310–6411	Try total, then aggregate premiums + investment income + fees
reit	6500–6553	Lease revenue + other income
utility	4900–4991	Electric + gas utility revenue

XBRL concept dictionary

xbrl_mappings.py maps ~250 XBRL concepts to 20+ standardized metrics. Each metric has an ordered list of concepts to try — earlier entries are preferred. Some entries are marked aggregate=True (sum all matching, used for multi-component revenue like banks).

Validation rules

Every extraction runs these checks:

1. revenue ≥ net income (when both positive) — catches segment-only revenue
2. Assets = Liabilities + Equity (within 5%) — catches mismatched concepts
3. Revenue not null — warns if no concept matched
4. Bank segment check — flags if bank revenue < 80% of net income
5. Gross margin 0–100% — for standard companies

Warnings are returned in the validation array so the AI can explain or retry.

Usage

Run as MCP server (STDIO)

python -m sec_mcp.server

Using with your app (Cursor, Claude Desktop, etc.)

1. Configure MCP so your app starts the SEC-MCP server (see below).
2. Set EDGAR_IDENTITY in .env or in the MCP server env.
3. The AI chooses the right tool per request:
   • "Apple's financials" → get_financials("AAPL")
   • "Compare AAPL vs MSFT vs GOOGL" → compare_companies(["AAPL","MSFT","GOOGL"])
   • "Morgan Stanley income statement" → get_income_statement("MS")
   • "What are Apple's risk factors?" → get_filing_text with section='risk factors'

Cursor / Claude Desktop configuration

{
  "mcpServers": {
    "sec-mcp": {
      "command": "python",
      "args": ["-m", "sec_mcp.server"],
      "cwd": "/path/to/SEC-MCP",
      "env": {
        "EDGAR_IDENTITY": "Your Name your@email.com"
      }
    }
  }
}

Configuration

Variable	Default	Description
EDGAR_IDENTITY	SEC-MCP sec-mcp@example.com	Your identity for SEC EDGAR API
SENTIMENT_MODEL	ProsusAI/finbert	Sentiment analysis model
SUMMARIZATION_MODEL	facebook/bart-large-cnn	Summarization model
NER_MODEL	dslim/bert-base-NER	NER model
MAX_CHUNK_TOKENS	512	Max tokens per chunk
CHUNK_OVERLAP_TOKENS	128	Overlap between chunks

Architecture

src/sec_mcp/
├── server.py           # MCP tool definitions (14 tools)
├── edgar_client.py     # EDGAR API wrapper (company search, filings, text)
├── financials.py       # Standardized extraction engine + validation
├── xbrl_mappings.py    # XBRL concept → metric dictionary (5 industry classes)
├── models.py           # Pydantic models (StandardizedFinancials, ratios, etc.)
├── config.py           # Environment config
└── nlp/
    ├── sentiment.py    # FinBERT
    ├── summarizer.py   # BART
    └── ner.py          # NER

NLP Models

Models are lazy-loaded (downloaded on first use, ~2.5GB total):

• ProsusAI/finbert — Financial sentiment, trained on SEC filings
• facebook/bart-large-cnn — Abstractive summarization
• dslim/bert-base-NER — Named entity recognition

Development

# Run tests
pytest

# Run tests (skip slow model tests)
pytest -m "not slow"

# Lint
ruff check src/ tests/

License

MIT