@pipeworx/cnmv-filings

Spanish listed-company regulated disclosures and annual financial reports from the CNMV (Comisión Nacional del Mercado de Valores) public registers, including the ESEF report packages. Filings show up within minutes of registration, not months later as in the community ESEF index.

Part of Pipeworx — an MCP gateway connecting AI agents to 1683+ live data sources.

Tools

• cnmv_search_filings(date_from?, date_to?, nif?, isin?, company?, feed?, limit?) searches disclosures by publication window (Madrid calendar days, inclusive, default the last 7 days). You can narrow it to one issuer. It covers "Otra información relevante" (results, annual and half-year report notices, buybacks, governance) and "Información privilegiada" (inside information), newest first. Each row has the company, NIF, category, title, registration number, a Madrid-time published_at and the document URL. total_count is exact for the window.
• cnmv_annual_reports(nif? | isin? | company?, limit?) returns the issuer's annual financial report register: financial-year end, publication date, auditor, audit opinion, the individual and consolidated report links, and the ESEF report package URL (a ZIP, sometimes named .xbri, holding the iXBRL report and taxonomy files, FY2020 onward).
• cnmv_find_issuer(company? | isin?) resolves a name or a Spanish ISIN to the NIF that the CNMV registers use.

Why this pack exists

esef-filings proxies filings.xbrl.org. On 2026-09-23 that index held 113 Spanish filings for FY2024 and 1 for FY2025. The CNMV is the primary source the index aggregates from. Measured the same day: Técnicas Reunidas' FY2025 annual financial report was registered 2026-02-26 21:25 Madrid time, and its ESEF ZIP (5.5 MB, LEI 213800JEZBUPZKWJGF49) downloads from the URL cnmv_annual_reports returns. The newest OIR row in the register was 19:48 the same day it was queried.

⚠️ Things a caller must know

1. This is a document index, not an XBRL-facts API. Nothing here parses the ESEF package. esef_package_url is there so a downstream pipeline can ingest it.
2. The issuer key is the Spanish NIF (e.g. A-28092583, sometimes written without the dash, e.g. A39000013). ISINs and LEIs are not the register's key. isin is resolved through the CNMV ISIN register, which lists only securities issued in Spain. A foreign issuer listed in Madrid has an N… NIF and no Spanish ISIN, so use company or nif for those.
3. Name search can match several entities. "banco santander" matches six, including foreign-currency listings with codes like BRL-000356. The pack picks the closest domestic name and lists the rest under issuer_candidates. Check them if the name is ambiguous.
4. Timestamps are Madrid local time on the source. published_at carries the +01:00/+02:00 offset. published_local is the raw string.

Auth

Keyless. No account, no API key. Everything is public on cnmv.es.

Data sources

• https://www.cnmv.es/portal/otra-informacion-relevante/resultado-oir.aspx?fechaDesde=DD/MM/YYYY&fechaHasta=DD/MM/YYYY[&nif=…][&page=N] is the "Otra información relevante" register, 10 rows per page, with a 0-based page.
• https://www.cnmv.es/portal/informacion-privilegiada/resultado-ip.aspx is the "Información privilegiada" register and takes the same parameters.
• https://www.cnmv.es/portal/consultas/ifa/listadoifa.aspx?id=0&nif=… is the annual financial report register for one issuer.
• https://www.cnmv.es/portal/Consultas/BusquedaPorEntidad is the entity name search (an ASP.NET postback).
• https://www.cnmv.es/portal/ancv/isin?isin=… is the ISIN register.
• https://www.cnmv.es/webservices/verdocumento/ver?t=…|e=… is the document download handler (PDF / ZIP). These URLs stayed stable across page loads when tested.

Gotchas

• 403 with errorcode=CVFE is the portal's not-found page, not a block. Its text reads "No ha sido posible completar su consulta. Verifique la ruta." A made-up path (/portal/nonexistent-xyz.aspx) returns the same response. The old HR/ComunicacionesRR.aspx and Consultas/IFA/InformesFinancierosAnuales.aspx paths return it because they do not exist. The pre-2020 "Hechos relevantes" feed was split into OIR and IP on 2020-02-08. The pack turns this response into a not_found: error.
• listadoifa.aspx without nif returns 400 errorcode=HE.
• The .aspx URLs 301 to extensionless ones, so follow redirects.
• The OIR/IP result pages report "Página 1 de N" but no row count. The pack computes the exact total as (N-1)*10 + rows on the last page, which costs one extra request when the window spans more pages than limit needs.
• The "Últimos días" summary page (Consultas/BusquedaUltimosDias.aspx) counts issuers per category per day, not filings. Its numbers are lower than total_count for the same day, and that is expected.
• Entity search needs WebForms state. POST back __VIEWSTATE, __VIEWSTATEGENERATOR and __EVENTVALIDATION, form-encoded, so the $ in control names goes out as %24 (the working encoding here; a literal $ was not tested on CNMV, but on other WebForms sites it silently re-renders the form with HTTP 200). A unique match redirects to the entity page. Several matches render a select list of NIF → name.

Quick Start

Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "cnmv-filings": {
      "url": "https://gateway.pipeworx.io/cnmv-filings/mcp"
    }
  }
}

What this endpoint actually serves

tools/list at https://gateway.pipeworx.io/cnmv-filings/mcp returns the tools in the table above plus the shared Pipeworx meta-tools — ask_pipeworx, discover_tools, search_within, remember/recall and the rest of the gateway-wide set. So the tool count you see is larger than this table: a single-pack endpoint currently lists roughly 30 shared tools alongside the pack's own. The connection's initialize response states its exact scope, and is the authoritative answer for a given day.

This is deliberate, not multiplexing by accident. The meta-tools are what let a scoped connection answer a question this pack does not cover — via ask_pipeworx, which routes across the whole catalog — without you adding a second MCP server. There is currently no way to mount a pack endpoint without them; if the extra schemas cost you more context than the routing is worth, connect to the full gateway once rather than to several pack endpoints.

Or connect to the full Pipeworx gateway to get every pack's tools listed directly, instead of just this one's:

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

Both URLs reach the same gateway and the same 1683+ data sources. The only difference is which pack's tools are listed directly; ask_pipeworx reaches all of them from either one.

No MCP client? Call it over HTTP

curl -X POST https://gateway.pipeworx.io/v1/tools/cnmv_search_filings \
  -H 'Content-Type: application/json' \
  -d '{"date_from":"2026-09-21","date_to":"2026-09-23","limit":5}'

No account needed for the first calls. Inspect any tool: GET https://gateway.pipeworx.io/v1/tools/cnmv_search_filings. Find one: POST https://gateway.pipeworx.io/v1/tools/search_packs with {"query":"..."}.

Standalone (no gateway account)

This package also runs as a local stdio MCP server — no Pipeworx account, no gateway round-trip:

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

Or run it directly to confirm it starts:

npx -y @pipeworx/mcp-cnmv-filings

It speaks MCP over stdin/stdout and answers initialize/tools/list/tools/call for only this pack's tools — none of the shared meta-tools the gateway connection above adds. Same source, same tools, no ask_pipeworx routing.

Using with ask_pipeworx

Instead of calling tools directly, you can ask questions in plain English — this works on the pack endpoint above as well as on the full gateway:

ask_pipeworx({ question: "your question about Cnmv Filings data" })

The gateway picks the right tool and fills the arguments automatically.

More

• Docs and guides
• pipeworx.io

License

MIT