# sareegpt/edgartools-mcp architecture

> Architecture diagram of the GitHub repository sareegpt/edgartools-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sareegpt/edgartools-mcp
- Repository: https://github.com/sareegpt/edgartools-mcp

## Overview

EdgarTools is a Python library for retrieving SEC EDGAR filings and turning them into structured company, filing, ownership, fund, and financial data. The principal workflow is to identify a company or request filings, retrieve filing content, parse it into domain objects, then analyze or render the results. The README also documents XBRL statements and cross-company facts, specialized form parsers, document search, and an MCP interface for AI agents. Connections beyond the excerpts rely on README statements or SOURCE INDEX references; unsampled internals are not treated as inspected.

Main entry points: [`edgar/_filings.py`](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/_filings.py) (Filing retrieval), [`edgar/__init__.py`](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/__init__.py) (Python API), [`edgar/entity/core.py`](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/entity/core.py) (Company identity), [`edgar/httpclient.py`](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/httpclient.py) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["SEC access"]
  node_public_api["Python API<br/>[__init__.py]"]
  node_sec(("SEC EDGAR"))
  node_http["HTTP client<br/>[httpclient.py]"]
  node_storage[("Filing storage<br/>[filesystem.py]")]
end

subgraph group_company["Company and filings"]
  node_entity["Company identity<br/>[core.py]"]
  node_tickers["Ticker lookup<br/>[tickers.py]"]
  node_filings["Filing retrieval<br/>[_filings.py]"]
  node_current["Current filings<br/>[current_filings.py]"]
  node_html["Filing documents<br/>[html_documents.py]"]
  node_display["Result formatting<br/>[formatting.py]"]
end

subgraph group_analysis["Financial analysis"]
  node_facts["Company facts<br/>[entity_facts.py]"]
  node_fact_query["Fact queries<br/>[query.py]"]
  node_statements["XBRL statements<br/>[statements.py]"]
  node_financials["Financial reports<br/>[financials.py]"]
end

subgraph group_forms["Specialized filings"]
  node_form_objects["Form data objects<br/>[current_report.py]"]
  node_ownership["Insider ownership<br/>[ownershipforms.py]"]
  node_thirteenf["13F holdings<br/>[models.py]"]
  node_fund_reports["Fund reports<br/>[reports.py]"]
end

subgraph group_ai["AI and documents"]
  node_document_search["Document search<br/>[search.py]"]
  node_text_search["Text search<br/>[textsearch.py]"]
  node_mcp["MCP server<br/>[server.py]"]
  node_mcp_tools["MCP tools<br/>[base.py]"]
end

node_analyst(("Analyst or agent"))

node_analyst -->|"uses"| node_public_api
node_public_api -->|"finds company"| node_entity
node_entity -->|"resolves ticker"| node_tickers
node_analyst -->|"requests filings"| node_public_api
node_public_api -->|"gets filings"| node_filings
node_public_api -->|"gets latest"| node_current
node_filings -->|"requests content"| node_http
node_http -->|"fetches SEC data"| node_sec
node_filings -.->|"uses storage"| node_storage
node_filings -->|"opens documents"| node_html
node_html -.->|"searches parsed text"| node_document_search
node_analyst -->|"searches documents"| node_document_search
node_analyst -->|"searches text"| node_text_search
node_entity -->|"accesses facts"| node_facts
node_facts -->|"filters facts"| node_fact_query
node_analyst -->|"requests statements"| node_financials
node_financials -.->|"parses XBRL"| node_statements
node_analyst -->|"parses 8-K"| node_form_objects
node_filings -->|"parses Form 4"| node_ownership
node_analyst -->|"reads holdings"| node_thirteenf
node_analyst -.->|"reads fund reports"| node_fund_reports
node_filings -->|"renders results"| node_display
node_analyst -->|"connects via MCP"| node_mcp
node_mcp -->|"routes tools"| node_mcp_tools
node_mcp_tools -->|"queries company"| node_entity

click node_public_api "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/__init__.py"
click node_entity "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/entity/core.py"
click node_tickers "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/reference/tickers.py"
click node_filings "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/_filings.py"
click node_current "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/current_filings.py"
click node_http "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/httpclient.py"
click node_storage "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/filesystem.py"
click node_html "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/files/html_documents.py"
click node_document_search "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/documents/search.py"
click node_text_search "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/search/textsearch.py"
click node_facts "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/entity/entity_facts.py"
click node_fact_query "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/entity/query.py"
click node_statements "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/xbrl/statements.py"
click node_financials "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/financials.py"
click node_form_objects "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/company_reports/current_report.py"
click node_ownership "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/ownership/ownershipforms.py"
click node_thirteenf "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/thirteenf/models.py"
click node_fund_reports "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/funds/reports.py"
click node_display "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/display/formatting.py"
click node_mcp "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/ai/mcp/server.py"
click node_mcp_tools "https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/ai/mcp/tools/base.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_sec,node_http,node_storage toneBlue
class node_entity,node_tickers,node_filings,node_current,node_html,node_display toneAmber
class node_facts,node_fact_query,node_statements,node_financials toneMint
class node_form_objects,node_ownership,node_thirteenf,node_fund_reports toneRose
class node_document_search,node_text_search,node_mcp,node_mcp_tools,node_analyst toneIndigo
```

## Components

### SEC access

- [Python API](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/__init__.py): `edgar/__init__.py`
- **SEC EDGAR**
- [HTTP client](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/httpclient.py): `edgar/httpclient.py`
- [Filing storage](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/filesystem.py): `edgar/filesystem.py`

### Company and filings

- [Company identity](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/entity/core.py): `edgar/entity/core.py`
- [Ticker lookup](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/reference/tickers.py): `edgar/reference/tickers.py`
- [Filing retrieval](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/_filings.py): `edgar/_filings.py`
- [Current filings](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/current_filings.py): `edgar/current_filings.py`
- [Filing documents](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/files/html_documents.py): `edgar/files/html_documents.py`
- [Result formatting](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/display/formatting.py): `edgar/display/formatting.py`

### Financial analysis

- [Company facts](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/entity/entity_facts.py): `edgar/entity/entity_facts.py`
- [Fact queries](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/entity/query.py): `edgar/entity/query.py`
- [XBRL statements](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/xbrl/statements.py): `edgar/xbrl/statements.py`
- [Financial reports](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/financials.py): `edgar/financials.py`

### Specialized filings

- [Form data objects](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/company_reports/current_report.py): `edgar/company_reports/current_report.py`
- [Insider ownership](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/ownership/ownershipforms.py): `edgar/ownership/ownershipforms.py`
- [13F holdings](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/thirteenf/models.py): `edgar/thirteenf/models.py`
- [Fund reports](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/funds/reports.py): `edgar/funds/reports.py`

### AI and documents

- [Document search](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/documents/search.py): `edgar/documents/search.py`
- [Text search](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/search/textsearch.py): `edgar/search/textsearch.py`
- [MCP server](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/ai/mcp/server.py): `edgar/ai/mcp/server.py`
- [MCP tools](https://github.com/sareegpt/edgartools-mcp/blob/main/edgar/ai/mcp/tools/base.py): `edgar/ai/mcp/tools/base.py`

### Other components

- **Analyst or agent**

## Connections

- Analyst or agent → Python API: uses
- Python API → Company identity: finds company (evidence: `edgar/__init__.py`)
- Company identity → Ticker lookup: resolves ticker
- Analyst or agent → Python API: requests filings
- Python API → Filing retrieval: gets filings (evidence: `edgar/__init__.py`)
- Python API → Current filings: gets latest (evidence: `edgar/__init__.py`)
- Filing retrieval → HTTP client: requests content (evidence: `edgar/_filings.py`)
- HTTP client → SEC EDGAR: fetches SEC data
- Filing retrieval → Filing storage: uses storage (evidence: `edgar/_filings.py`)
- Filing retrieval → Filing documents: opens documents (evidence: `edgar/_filings.py`)
- Filing documents → Document search: searches parsed text
- Analyst or agent → Document search: searches documents (evidence: `edgar/documents/search.py`)
- Analyst or agent → Text search: searches text (evidence: `edgar/search/textsearch.py`)
- Company identity → Company facts: accesses facts (evidence: `edgar/entity/__init__.py`)
- Company facts → Fact queries: filters facts (evidence: `edgar/entity/query.py`)
- Analyst or agent → Financial reports: requests statements
- Financial reports → XBRL statements: parses XBRL
- Analyst or agent → Form data objects: parses 8-K
- Filing retrieval → Insider ownership: parses Form 4 (evidence: `edgar/_filings.py`)
- Analyst or agent → 13F holdings: reads holdings
- Analyst or agent → Fund reports: reads fund reports
- Filing retrieval → Result formatting: renders results (evidence: `edgar/_filings.py`)
- Analyst or agent → MCP server: connects via MCP
- MCP server → MCP tools: routes tools (evidence: `edgar/ai/mcp/server.py`)
- MCP tools → Company identity: queries company (evidence: `edgar/ai/mcp/tools/base.py`)
