convez.ai
MCP ServerFinanceiroAvançado
Aomala

SEC-MCP: Análise de Documentos Financeiros da SEC

Aomala/SEC-MCP

Extração e análise inteligente de documentos SEC com NLP financeiro

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para análise de arquivos SEC (10-K, 10-Q, 8-K) com extração financeira consciente de indústria e NLP baseado em BERT. Oferece busca de empresas, extração de dados financeiros padronizados com validação, análise de sentimento FinBERT e sumarização BART para relatórios regulatórios.

Instalação

$npx convez-ai Aomala/SEC-MCP

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
1
Saúde
28%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Análise automatizada de demonstrações financeiras de empresas listadas
  • Extração de fatores de risco e análise de sentimento em relatórios 10-K/10-Q
  • Comparação de métricas financeiras entre múltiplas empresas com validação automática
  • Processamento em lote de documentos financeiros para pesquisa ou due diligence

Veredito

Solução robusta e especializada para análise de filing financeiro, com suporte a múltiplas indústrias e validação automática de dados. Ideal para pesquisadores, analistas quantitativos e plataformas de FinTech que precisam extrair insights estruturados de documentos SEC em escala.

README

A tradução para o português deste README ainda está na fila.

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

ToolDescription
search_companySearch by ticker/name → CIK, ticker, SIC code, industry
get_filing_listList filings, filter by form type (10-K, 10-Q, 8-K)

Financials (standardized, industry-aware, validated)

ToolDescription
get_financialsFull standardized extraction: metrics, ratios, validation, opt. statements
get_financials_batchSame as above for N tickers in parallel
get_income_statementJust the income statement rows
get_balance_sheetJust the balance sheet rows
get_cash_flowJust the cash flow rows
get_financial_ratiosJust computed ratios (margins, ROA, ROE, leverage, etc.)
compare_companiesSide-by-side metrics + ratios for multiple tickers

Filing Text

ToolDescription
get_filing_textFull filing or specific section text (supports aliases like 'risk factors')

NLP Analysis

ToolDescription
analyze_sentimentFinBERT sentiment on text or filing section
summarize_filingHierarchical BART summarization
extract_entitiesNER (ORG, PER, LOC, MONEY, DATE, PERCENT)
analyze_filingCombined 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:

ClassSIC RangeRevenue Strategy
standardEverything elseFirst match: Revenues, RevenueFromContractWithCustomer, SalesRevenueNet, …
bank6020–6299Try total (Revenues, NetRevenues), then aggregate NII + non-interest + trading + fees
insurance6310–6411Try total, then aggregate premiums + investment income + fees
reit6500–6553Lease revenue + other income
utility4900–4991Electric + 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

VariableDefaultDescription
EDGAR_IDENTITYSEC-MCP sec-mcp@example.comYour identity for SEC EDGAR API
SENTIMENT_MODELProsusAI/finbertSentiment analysis model
SUMMARIZATION_MODELfacebook/bart-large-cnnSummarization model
NER_MODELdslim/bert-base-NERNER model
MAX_CHUNK_TOKENS512Max tokens per chunk
CHUNK_OVERLAP_TOKENS128Overlap 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

Ver o original no GitHub

Bom para

Relacionados