# Esef Filings [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/pipeworx-io/mcp-esef-filings  
**GitHub Stars:** 1  
**npm Downloads (last month):** 1297  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/esef-filings

## Description
XBRL filings index MCP — wraps the filings.xbrl.org JSON:API index run by

## Tools
Capabilities this server exposes over MCP:

- **esef_search_filings** — Search the XBRL International filings index (filings.xbrl.org) for published company annual reports. Answers "which European companies have filed an annual report for 2023", "does Nokia have an ESEF filing", "list Finnish filings with validation errors", "Portuguese filings with a period end after 2024-06-30", "Spanish annual reports for 2025". Returns per filing: company name, LEI or national identifier, country, reporting regime, period end, source (xbrl.org, cmvm, cnmv, newsweb or fi) and official publication time where known, XBRL validation error/warning counts, report language, and direct links to the machine-readable xBRL-JSON, the inline-XBRL HTML report and the viewer. Filter by company name (substring), country (ISO-2), regime, exact period end date, calendar year, or a period_end_from/period_end_to date range. Any other argument name is rejected with a user_error rather than silently ignored. Covers 25,640 filings in two regimes: ESEF (~16,000 annual financial reports from 19 European countries — AT BE CY CZ DK ES FI FR GB GR IS IT LT NL NO PL PT RO SE) and UAIFRS (~9,600 Ukrainian IFRS filings, country UA). Pass `country` or `regime` to pin the scope you mean. Portuguese (PT), Spanish (ES) and Norwegian (NO) ESEF reports are also read directly from where each country publishes them — CMVM for Portugal, CNMV for Spain, Oslo Børs NewsWeb for Norway — so PT, ES and NO coverage follows official publication (typically within a day) rather than the index's months-long lag; each row names its `source` and those rows carry the official `published_at`. Swedish (SE) reports are likewise read from Finansinspektionen (FI), the Swedish OAM, which is the only source for Swedish FY2025 reports, Belgian (BE) reports from the FSMA's STORI database, the Belgian OAM, Maltese (MT) reports from the Malta Stock Exchange OAM, the only source for Maltese FY2025 reports, Croatian (HR) reports from HANFA's SRPI, the Croatian OAM and the only source for Croatian FY2025 reports, Hungarian (HU) reports from the MNB's Közzétételek site, the Hungarian OAM and the only source for Hungarian FY2025 reports, Lithuanian (LT) reports from oam.lt, the Lithuanian OAM run by Nasdaq Vilnius, as well as the index, Romanian (RO) reports from the ASF OAM, the only source for Romanian FY2025 reports, Cypriot (CY) reports from the Cyprus Stock Exchange public OAM, the only source for Cypriot FY2025 reports, and Latvian (LV) reports from CSRI, the Latvian OAM, the only source for Latvian FY2024 and FY2025 reports. Luxembourgish (LU), Slovenian (SI) and Estonian (EE) reports are also answered directly from the LuxSE OAM, SEOnet or the Estonian FSA's OAM for each request, because these three OAMs' terms require the operator's consent for commercial reuse of their documents beyond ordinary access; a lookup made once on a caller's behalf is not that. Greek (GR) and Irish (IE) reports are likewise answered directly from Euronext Athens and the Euronext Dublin OAM for each request — these two sites' terms forbid bots and automated access outright rather than just reuse, so these are Bruce-authorized live lookups rather than a re-derivation of the usual reasoning, kept live and never mirrored for the same reason. Bulgarian (BG) reports are answered directly from BEIS, a Bulgarian disclosure agent whose terms ask only for attribution (unlike Bulgaria's other disclosure agents, which this pack does not call) and covers only the roughly three issuers that use it. None of GR/IE/BG carry machine-readable facts (esef_filing_facts declines a live-lookup id and points at its `package_url`/`source_url`); SI is limited to the ~20 most recent Slovenian annual-report announcements; IE rows carry no `period_end` (Irish fiscal year ends vary by issuer); GR's `period_end` is inferred from the filing's reporting year, not stated exactly, and flagged `period_end_inferred`. All six (LU, SI, EE, GR, IE, BG) are pinned-country lookups only — pass `country` explicitly. Coverage of the current calendar year is sparse — the index lags the filing season; see the response `coverage_note`. Reports the index-wide match count and echoes back proof that the filters actually applied. Follow up with esef_filing_facts to get the numbers inside a filing.
- **esef_entity_filings** — List every annual report one company has published to the XBRL International filings index, resolving a company name, LEI, or national registration number to the filer. Answers "what years has Citycon filed?" or "give me Nokia's latest annual report". Returns the resolved company (name, identifier, and how the match was made) plus each filing with period end, country, regime, validation error/warning counts and links to the xBRL-JSON, HTML report and viewer. Covers 25,640 filings in two regimes: ESEF (~16,000 annual financial reports from 19 European countries — AT BE CY CZ DK ES FI FR GB GR IS IT LT NL NO PL PT RO SE) and UAIFRS (~9,600 Ukrainian IFRS filings, country UA). Pass `country` or `regime` to pin the scope you mean. Portuguese (PT), Spanish (ES) and Norwegian (NO) ESEF reports are also read directly from where each country publishes them — CMVM for Portugal, CNMV for Spain, Oslo Børs NewsWeb for Norway — so PT, ES and NO coverage follows official publication (typically within a day) rather than the index's months-long lag; each row names its `source` and those rows carry the official `published_at`. Swedish (SE) reports are likewise read from Finansinspektionen (FI), the Swedish OAM, which is the only source for Swedish FY2025 reports, Belgian (BE) reports from the FSMA's STORI database, the Belgian OAM, Maltese (MT) reports from the Malta Stock Exchange OAM, the only source for Maltese FY2025 reports, Croatian (HR) reports from HANFA's SRPI, the Croatian OAM and the only source for Croatian FY2025 reports, Hungarian (HU) reports from the MNB's Közzétételek site, the Hungarian OAM and the only source for Hungarian FY2025 reports, Lithuanian (LT) reports from oam.lt, the Lithuanian OAM run by Nasdaq Vilnius, as well as the index, Romanian (RO) reports from the ASF OAM, the only source for Romanian FY2025 reports, Cypriot (CY) reports from the Cyprus Stock Exchange public OAM, the only source for Cypriot FY2025 reports, and Latvian (LV) reports from CSRI, the Latvian OAM, the only source for Latvian FY2024 and FY2025 reports. Luxembourgish (LU), Slovenian (SI) and Estonian (EE) reports are also answered directly from the LuxSE OAM, SEOnet or the Estonian FSA's OAM for each request, because these three OAMs' terms require the operator's consent for commercial reuse of their documents beyond ordinary access; a lookup made once on a caller's behalf is not that. Greek (GR) and Irish (IE) reports are likewise answered directly from Euronext Athens and the Euronext Dublin OAM for each request — these two sites' terms forbid bots and automated access outright rather than just reuse, so these are Bruce-authorized live lookups rather than a re-derivation of the usual reasoning, kept live and never mirrored for the same reason. Bulgarian (BG) reports are answered directly from BEIS, a Bulgarian disclosure agent whose terms ask only for attribution (unlike Bulgaria's other disclosure agents, which this pack does not call) and covers only the roughly three issuers that use it. None of GR/IE/BG carry machine-readable facts (esef_filing_facts declines a live-lookup id and points at its `package_url`/`source_url`); SI is limited to the ~20 most recent Slovenian annual-report announcements; IE rows carry no `period_end` (Irish fiscal year ends vary by issuer); GR's `period_end` is inferred from the filing's reporting year, not stated exactly, and flagged `period_end_inferred`. All six (LU, SI, EE, GR, IE, BG) are pinned-country lookups only — pass `country` explicitly. The same annual report is frequently indexed once per language edition (a Finnish and an English row for one financial year), so results are also grouped into distinct reports with the English edition preferred, and both a filing count and a distinct-report count are returned.
- **esef_filing_facts** — Read the actual IFRS financial facts out of one published annual report — revenue, profit or loss, total assets, equity, operating cash flow, earnings per share and every other tagged figure, with the currency, the exact reporting period and the XBRL concept name. This is the numbers hop: esef_search_filings and esef_entity_filings prove a filing exists, this one opens its machine-readable xBRL-JSON report and returns what the company reported. Covers 25,640 filings in two regimes: ESEF (~16,000 annual financial reports from 19 European countries — AT BE CY CZ DK ES FI FR GB GR IS IT LT NL NO PL PT RO SE) and UAIFRS (~9,600 Ukrainian IFRS filings, country UA). Pass `country` or `regime` to pin the scope you mean. Portuguese (PT), Spanish (ES) and Norwegian (NO) ESEF reports are also read directly from where each country publishes them — CMVM for Portugal, CNMV for Spain, Oslo Børs NewsWeb for Norway — so PT, ES and NO coverage follows official publication (typically within a day) rather than the index's months-long lag; each row names its `source` and those rows carry the official `published_at`. Swedish (SE) reports are likewise read from Finansinspektionen (FI), the Swedish OAM, which is the only source for Swedish FY2025 reports, Belgian (BE) reports from the FSMA's STORI database, the Belgian OAM, Maltese (MT) reports from the Malta Stock Exchange OAM, the only source for Maltese FY2025 reports, Croatian (HR) reports from HANFA's SRPI, the Croatian OAM and the only source for Croatian FY2025 reports, Hungarian (HU) reports from the MNB's Közzétételek site, the Hungarian OAM and the only source for Hungarian FY2025 reports, Lithuanian (LT) reports from oam.lt, the Lithuanian OAM run by Nasdaq Vilnius, as well as the index, Romanian (RO) reports from the ASF OAM, the only source for Romanian FY2025 reports, Cypriot (CY) reports from the Cyprus Stock Exchange public OAM, the only source for Cypriot FY2025 reports, and Latvian (LV) reports from CSRI, the Latvian OAM, the only source for Latvian FY2024 and FY2025 reports. Luxembourgish (LU), Slovenian (SI) and Estonian (EE) reports are also answered directly from the LuxSE OAM, SEOnet or the Estonian FSA's OAM for each request, because these three OAMs' terms require the operator's consent for commercial reuse of their documents beyond ordinary access; a lookup made once on a caller's behalf is not that. Greek (GR) and Irish (IE) reports are likewise answered directly from Euronext Athens and the Euronext Dublin OAM for each request — these two sites' terms forbid bots and automated access outright rather than just reuse, so these are Bruce-authorized live lookups rather than a re-derivation of the usual reasoning, kept live and never mirrored for the same reason. Bulgarian (BG) reports are answered directly from BEIS, a Bulgarian disclosure agent whose terms ask only for attribution (unlike Bulgaria's other disclosure agents, which this pack does not call) and covers only the roughly three issuers that use it. None of GR/IE/BG carry machine-readable facts (esef_filing_facts declines a live-lookup id and points at its `package_url`/`source_url`); SI is limited to the ~20 most recent Slovenian annual-report announcements; IE rows carry no `period_end` (Irish fiscal year ends vary by issuer); GR's `period_end` is inferred from the filing's reporting year, not stated exactly, and flagged `period_end_inferred`. All six (LU, SI, EE, GR, IE, BG) are pinned-country lookups only — pass `country` explicitly. Identify the filing by fxo_id from a search result (a Portuguese CMVM filing looks like "cmvm-1355933", a Spanish CNMV filing "cnmv-20912", a Norwegian NewsWeb filing "newsweb-668785-321602", a Swedish FI filing "fi-61807", a Belgian STORI filing "fsma-5c08f790-404c-4121-bd0b-0cf3350455da", a Maltese MSE filing "mse-BOV_20251231_CON_AFR_529900RWC8ZYB066JF16_20260326114707204", a Croatian SRPI filing "hanfa-1214588", a Hungarian MNB filing "mnb-909016", a Lithuanian oam.lt filing "oamlt-468051-338788", a Romanian ASF filing "asf-SNP-20260319180945", a Cypriot CSE filing "cse-222818-223858", a Latvian CSRI filing "csri-24777-1"), or just by company name or LEI plus an optional year and the latest matching report is used (the national copy for Portuguese, Spanish, Norwegian, Swedish, Belgian, Maltese, Croatian, Hungarian, Lithuanian, Romanian, Cypriot and Latvian issuers, otherwise the English-language edition). A live-lookup id from esef_search_filings/esef_entity_filings for Luxembourg, Slovenia, Estonia, Greece, Ireland or Bulgaria (fxo_id starting "luxoam-", "seonet-", "fi_ee-", "athex-", "oamie-" or "beis-") has no xBRL-JSON to read — this tool declines and points at that filing's `package_url`/`source_url` instead. Pass `concept` to pull one line item (case-insensitive substring of the IFRS concept, e.g. "Revenue", "ProfitLoss", "Assets", "Equity", "CashFlows"); omit it for a headline projection of the main statement figures. Facts repeated across statements are collapsed, consolidated totals are separated from segment and equity-component breakdowns, and the full concept inventory of the report is returned so a follow-up query can target any line item.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "esef-filings": {
    "command": "npx",
    "args": ["-y","@pipeworx/mcp-esef-filings"]
  }
}
```

## Documentation

## What Esef Filings does

Esef Filings provides MCP tools for finding published company annual reports and reading tagged financial data from those reports. Its main index covers two regimes: ESEF filings from European countries and UAIFRS filings from Ukraine. Results can include the company name, LEI or national identifier, country, reporting regime, reporting period, language, validation error and warning counts, source, publication time, and links to the machine-readable report, inline-XBRL document, viewer, or package.

The service is useful when an agent needs to answer questions such as which companies filed for a particular year, what reports a company has published, or what revenue, assets, equity, profit, cash flow, or earnings-per-share figures appear in a filing.

## How it works

Use `esef_search_filings` to filter the filing index by company-name substring, ISO-2 country code, regime, calendar year, exact period end, or a period-end date range. The response includes the index-wide match count and records how the requested filters were applied and verified. Unknown argument names produce a `user_error` instead of being dropped.

Use `esef_entity_filings` when the starting point is a company name, LEI, or national registration number. It resolves the entity and returns its filing history, including how the match was made. Language editions of the same annual report are grouped into distinct reports, with the English edition preferred when available.

Use `esef_filing_facts` as the numbers step. It opens a filing's xBRL-JSON report and returns tagged IFRS facts with their value, currency, reporting period, and concept name. A filing can be identified with an `fxo_id`, or by company and optional year. Supplying a concept substring narrows the result; omitting it returns a headline selection and the report's concept inventory.

## Tools and capabilities

- `esef_search_filings` searches annual-report metadata and supports country, regime, year, period, validation-error, sorting, pagination, and date-range filters.
- `esef_entity_filings` resolves a company identifier and lists its annual reports with grouped language editions.
- `esef_filing_facts` reads financial facts from xBRL-JSON, including common statement figures and other tagged concepts.
- Search and entity results provide direct links to machine-readable, HTML, viewer, and package resources when available.
- Fact extraction collapses repeated identical taggings, separates consolidated totals from dimensional breakdowns, and exposes conflicting values rather than silently choosing between them.

## Limitations and notes

The indexed scope contains approximately 25,640 filings across ESEF and UAIFRS; an unfiltered request can therefore include Ukrainian filings as well as European reports. Pin `country` or `regime` when the distinction matters. The index may lag the filing season, while several countries are queried directly from national OAMs or disclosure services to improve recent coverage.

Some live-lookup countries require an explicit `country` filter. Luxembourg, Slovenia, Estonia, Greece, Ireland, and Bulgaria have special lookup behavior, and certain results from those sources do not provide machine-readable xBRL-JSON for `esef_filing_facts`. Irish rows may lack an exact period end, Greek periods can be inferred from the reporting year, and Slovenian coverage is limited to roughly the most recent announcements.

A small portion of index rows lack a machine-readable report. In that case, fact extraction returns a not-found result with any surviving source URLs. Dimensioned facts are excluded by default, text-valued facts are clipped, and contradictory values are surfaced as conflicts. Period normalization also accounts for the one-day timestamp convention used by xBRL instant periods.

_Full upstream README: https://allmcps.com/mcp/esef-filings/readme_