edgar-link

Analyst-grade SEC EDGAR financials. A Python library, CLI, and MCP server that pulls XBRL filings directly from the SEC and layers an analyst-normalized metric engine on top.

Unlike raw filing tools, edgar-link aims to return usable financial outputs such as normalized revenue, EBIT, EBITDA, FCF, leverage, margins, returns, growth, LTM rollups, and structural balance-sheet / cash-flow buildups. It also includes 5-year peer beta / R^2 utilities. No API key, no subscription; the live data source is the SEC.

SEC identity required. SEC fair-access policy requires every requester to identify themselves. Before any live call, set:

export EDGAR_IDENTITY="Your Name your@email.com"   # macOS/Linux
$env:EDGAR_IDENTITY = "Your Name your@email.com"   # Windows PowerShell

Without it the SEC will throttle requests. Do not hardcode, borrow, or commit someone else's identity. SEC_EDGAR_USER_AGENT is also accepted as an alias for compatibility with other SEC tooling.

What it does

• Looks up public companies by name or ticker and resolves them to SEC CIKs
• Pulls Company Facts and Company Concept data from the SEC XBRL APIs
• Normalizes issuer-specific XBRL tags into reusable statement data
• Computes analyst-normalized derived metrics on top of that normalized data
• Builds structural balance-sheet and cash-flow statements from a frozen slot taxonomy
• Exposes the engine through a local CLI and an MCP server

SEC API usage

This project primarily uses the SEC XBRL APIs:

• Company Facts API
  • https://data.sec.gov/api/xbrl/companyfacts/CIK##########.json
  • Full XBRL fact history for a filer in one response
• Company Concept API
  • https://data.sec.gov/api/xbrl/companyconcept/CIK##########/taxonomy/tag.json
  • Historical values for one concept such as Assets or Revenues

The engine uses:

• request identification via EDGAR_IDENTITY
• local caching to reduce repeated pulls
• rate-limited access intended to stay within SEC fair-access expectations

More information: https://www.sec.gov/developer

Installation

Requirements

• Python 3.11+
• pip

The pinned dependency set (pandas, numpy) requires Python 3.11+, so 3.11 is the hard floor. The hash-verified clean-room install and CI path are validated on Windows / CPython 3.11 (requirements.lock is Windows/cp311-specific); a Linux lock is deferred until a fresh dependency resolve is safe under the active supply-chain incident policy.

Install from GitHub

No PyPI release yet.

# library + metric engine
pip install "git+https://github.com/jibarix/edgar-link.git#egg=edgar-link"

# with MCP support
pip install "edgar-link[mcp] @ git+https://github.com/jibarix/edgar-link.git"

Development install

git clone https://github.com/jibarix/edgar-link.git
cd edgar-link
python -m venv venv
venv\Scripts\activate          # Windows
# source venv/bin/activate     # macOS/Linux
pip install -e .

Dependencies are declared in pyproject.toml and pinned to reviewed versions. requirements.lock is the corresponding hash-pinned lockfile.

Usage

Three ways to drive the engine. They share the same Python core; pick the one that fits the workflow.

	Talk to Claude (MCP)	CLI	Library
Best for	Ad-hoc questions, exploration, no coding	One-shot pulls, scripted or scheduled exports	Building analyses, pipelines, custom code
Invocation	Natural-language prompt to an MCP client	python main.py ...	from edgar.metrics import ...
Setup	Install [mcp] extra, register the server once	Install the runtime	Install the runtime
Output	Conversational response in the client	Console table or Excel / CSV / JSON / HTML file	Python objects (dicts, DataFrames)
Lookup by	Name, ticker, or CIK	Name, ticker, or --cik	CIK (resolve names via edgar.company_lookup)
EDGAR_IDENTITY	In the MCP client's env config	In your shell env	In your shell env

Talk to Claude (MCP)

The conversational path. The same engine is exposed as an MCP stdio server, so an MCP-aware client (Claude Code, Claude Desktop) can call it directly in natural language:

• "Show Apple's last 3 fiscal years of revenue, EBIT, and FCF."
• "Compute ROIC for ticker MSFT, last 5 quarters."
• "Find software filers (SIC 7372) with U.S. revenue dominance."

Install and register the server once — see MCP server reference below — then just ask. No code from the caller.

CLI

Interactive mode:

python main.py

Command-line mode:

python main.py --company "Apple Inc" --statement-type BS --period-type annual --num-periods 3 --output-format excel

Supported statement types:

• BS - Balance Sheet
• IS - Income Statement
• CF - Cash Flow Statement
• EQ - Equity Statement
• CI - Comprehensive Income
• ALL - All supported statements

Library (Python import)

For building analyses on top of the engine in your own code:

from edgar.filing_retrieval import FilingRetrieval
from edgar.xbrl_parser import XBRLParser
from edgar.metrics import REGISTRY, NormalizedStatement, compute, list_slugs

filings = FilingRetrieval()
parser  = XBRLParser()

facts = filings.get_company_facts("0000320193")   # Apple Inc.
normalized = parser.parse_company_facts(
    facts,
    statement_type="IS",
    period_type="annual",
    num_periods=3,
)
ns = NormalizedStatement(normalized)

ebit_series   = compute("ebit", ns)               # {period: value}
margin_slugs  = list_slugs(category="margins")    # discover what's registered
spec          = REGISTRY["roic"]                  # MetricSpec (fn, unit, ...)

EDGAR_IDENTITY must be set in the environment for any live retrieval. See Architecture for module boundaries and MCP server reference for the equivalent tool surface.

MCP server reference

Install, registration, configuration, and the tool surface for the stdio server invoked via python -m edgar_mcp.

Install MCP extra

pip install -e ".[mcp]"

Register with Claude Code

claude mcp add edgar -e EDGAR_IDENTITY="Your Name your@email.com" -- python -m edgar_mcp

MCP config example

{
  "mcpServers": {
    "edgar": {
      "command": "python",
      "args": ["-m", "edgar_mcp"],
      "env": {
        "EDGAR_IDENTITY": "Your Name your@email.com"
      }
    }
  }
}

MCP tools

Tool	Purpose
lookup_company(query)	Resolve a name or ticker to SEC CIK candidates
get_financial_statement(cik_or_ticker, statement_type, period_type, num_periods)	Return normalized BS / IS / CF / EQ / CI / ALL data by period
get_concept(cik_or_ticker, concept, taxonomy)	Return a full historical time series for one XBRL concept
search_companies(sic, industry, country_inc, revenue_country, name_substring, limit)	Filter the local company classification index
list_metrics(category)	Enumerate registered derived metrics
compute_metric(slug, cik_or_ticker, period_type, num_periods)	Compute one derived metric series with the required internal lookback

search_companies reads data/company_index.json; build it first with:

python -m edgar.company_classifier --build

Companion Claude Skill

The MCP server gives Claude access to the engine; the bundled edgar-link-financials skill gives Claude the workflow knowledge to use it well. Together they mean a question like "show MSFT's ROIC over 5 quarters" resolves the ticker, computes the metric with the right internal lookback, and reports the result with units — without the user having to know tool names, that EBIT is analyst-normalized, or that search_companies needs a prebuilt index.

The skill is a portable folder (SKILL.md + references/) that works in Claude.ai, Claude Code, and the API. To use it in Claude Code, copy the folder into your skills directory, or upload it in Claude.ai via Settings → Capabilities → Skills. It triggers on financial / fundamentals / filings questions and defers detailed metric and error guidance to its references/ files (progressive disclosure), so it adds little to context until needed.

EDGAR_IDENTITY must still be set in the MCP server's environment — the skill documents that precondition but cannot supply the identity itself.

Architecture

1. Retrieval

• edgar/filing_retrieval.py
  • SEC submissions, Company Facts, Company Concept, filing instance retrieval
• edgar/company_lookup.py
  • ticker / company-name lookup and CIK resolution

2. Statement normalization

• edgar/xbrl_parser.py
  • converts Company Facts into categorized, periodized statement data
• edgar/tag_classifier.py
  • maps raw XBRL concepts into statement categories

3. Derived metrics

The metric engine is registry-based. Metric functions register themselves in edgar/metrics/registry.py, and the public surface is imported through edgar/metrics/__init__.py.

Main metric modules:

Module	Examples
derived_lines.py	revenue, gross_profit, ebit, ebitda, fcf, total_debt
margins.py	ebit_margin, ebitda_margin, ni_margin, fcf_margin
ratios.py	debt_to_capital, debt_to_equity, current_ratio, quick_ratio
returns.py	roa, roe, roic, asset_turnover
working_capital.py	dso, dio, dpo, cash_conversion_cycle
growth.py	<base>_growth, <base>_cagr_{3,5,7}y
ltm.py	trailing-twelve-months rollups

4. Structural BS / CF buildup

The repo also includes a second normalization path for balance-sheet and cash-flow structure:

• edgar/metrics/_statement_taxonomy.py
  • frozen closed-set slot taxonomy
• edgar/metrics/_bs_prefilter.py
  • deterministic balance-sheet tag prefilter with polarity guardrails
• edgar/metrics/_cf_prefilter.py
  • deterministic cash-flow tag prefilter with polarity guardrails
• edgar/metrics/statement_buildup.py
  • derives structural BS / CF buildups from raw Company Facts

Important design rule:

• reported subtotal tags are kept for provenance and drift checking
• they are not treated as raw input lines to be summed into the buildup

5. Beta utilities

edgar/metrics/beta.py computes 5-year monthly beta and R^2 versus the S&P 500 from Yahoo monthly bars.

What it does today:

• peer beta / R^2 regression
• one row per ticker
• aligned monthly return window

What it does not currently implement:

• bottom-up beta chain
• unlever -> cash-correct -> total-beta -> relever workflow

Analyst-normalized EBIT

derived_lines.ebit() is intentionally not just raw us-gaap:OperatingIncomeLoss.

Current normalization:

EBIT = OperatingIncomeLoss + goodwill_impairment + asset_impairment

This is meant to move the output closer to institutional analyst convention for names where unusual impairments sit inside reported operating income. A pretax-plus-interest fallback is also used for some hybrid-finance issuers that do not tag OperatingIncomeLoss cleanly.

Scripts

The current scripts/ directory is focused on validation, maintenance, and workbook/reporting workflows:

Script	Purpose
scripts/smoke_test_metrics.py	Live AAPL smoke test for the parser + metric registry. Prints a compact multi-period table of hand-checked metrics. Requires EDGAR_IDENTITY or SEC_EDGAR_USER_AGENT.
scripts/gen_lockfile.py	Regenerates `requirements