catalejo
Query Spanish CNMV filings through two MCP tools.
Fetch the latest filings, newest first, filtered by days and kind (
IP,OIR, or all).Fetch one issuer's filings by NIF (fast) or name, with kind, days/date range, and result limit.
Access both price-sensitive announcements and other regulatory announcements; IP history starts Feb 2020.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@catalejo What price-sensitive announcements has Cellnex filed since 2023?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
catalejo
catalejo (Spanish): spyglass.
Spain's securities regulator (CNMV) publishes everything listed companies have to disclose, but only through web forms and PDFs. catalejo turns that into clean Python objects, and plugs it into AI agents through an MCP server.
Think of it as a small SEC EDGAR for Spain.
Having had perfect understanding of all things from the very first, to write unto thee in order, that thou mightest know the certainty of those things. (Luke 1:3-4)

>>> import catalejo
>>> for f in catalejo.filings(days=7, kind="IP"):
... print(f.registered_at, f.issuer, "|", f.title)
2026-11-10 16:20:00+01:00 CONSTRUCCIONES Y AUXILIAR DE FERROCARRILES, S.A | El Consejo de Administración de la Sociedad ha aprobado el Plan Estratégico 2027-2030.
2026-11-09 12:14:00+01:00 ELECNOR, S.A. | Elecnor comunica la propuesta del Consejo de Administración de distribución de un dividendo ...Install
pip install catalejo # library + command line
pip install "catalejo[mcp]" # + MCP server for Claude and other agents
pip install "catalejo[pdf]" # + text extraction from filed PDFsPython 3.10+. Or try it without installing anything, with uv:
uvx catalejo filings --days 3 --kind IPRelated MCP server: edgar-mcp
Example: a takeover bid, as it happened
How BBVA's bid for Banco Sabadell started, straight from the official register, to the minute:
catalejo filings --issuer A08000143 --kind IP --since 2024-04-30 --until 2024-05-312024-05-09 07:06 IP BANCO DE SABADELL, S.A. (BA… BBVA comunica el anuncio previo de oferta pública voluntaria de adquisición de ac…
2024-05-08 08:28 IP BANCO DE SABADELL, S.A. Banco Sabadell remite la comunicación que recibió el Presidente del Consejo de Ad…
2024-05-06 19:11 IP BANCO DE SABADELL, S.A. Banco Sabadell comunica decisiones adoptadas por el Consejo de Administración.
2024-05-01 13:19 IP BANCO DE SABADELL, S.A. (BA… BBVA, S.A. comunica la carta enviada al Consejo de Administración de Banco de Sab…
2024-04-30 14:23 IP BANCO DE SABADELL, S.A. Banco Sabadell confirma que ha recibido una propuesta escrita indicativa de Banco…Each line links to the original filed document (--format json or csv to get the links). Note that BBVA's announcements appear under Sabadell: the CNMV files them under the company they are about.
What you can get
Price-sensitive announcements (IP) and other regulatory announcements (OIR), the two channels issuers use to disclose anything that can move the price: results, M&A, takeover bids, guidance, board changes, buybacks...
from datetime import date
import catalejo
catalejo.filings(days=3) # everything from the last 3 days, IP + OIR
catalejo.filings(days=30, kind="IP", issuer="cellnex")
# Full history for one company. Filtering by NIF (Spanish tax id) is done
# by the CNMV itself, so years of data come back in a few seconds.
catalejo.filings(since=date(2020, 1, 1), kind="IP", issuer="A64907306")Each Filing has kind, registered_at (timezone-aware, Madrid), issuer (the company the filing is about), issuer_nif, category, title, registry_number and document_url.
The text of the filed document:
f = catalejo.filings(days=10, kind="IP", issuer="A64907306")[0]
print(catalejo.document_text(f)) # needs catalejo[pdf]The securities (ISINs) of an issuer, shares and bonds:
>>> [s for s in catalejo.securities("A64907306") if s.is_share]
[Security(isin='ES0105066007', fisn='CLNX/AC 0.25', cfi='ESVUFB', ...)]Command line
catalejo filings --days 3 --kind IP # latest price-sensitive announcements
catalejo filings --issuer A48265169 --since 2020 --kind IP --format csv > bbva.csv
catalejo securities A64907306 --shares
catalejo text "<document_url of a filing>" # needs catalejo[pdf]--format csv or --format json for piping into other tools. catalejo --help for the rest.
Use it from Claude (MCP)
catalejo ships an MCP server with two tools, latest_filings and issuer_filings, so you can ask things like "What price-sensitive news has Cellnex published since 2023? Group it by topic." Results come with found, returned and complete, so the agent knows when a search was cut short.
Claude Desktop: add this to claude_desktop_config.json (Settings → Developer → Edit Config) and restart the app:
{
"mcpServers": {
"catalejo": {
"command": "uvx",
"args": ["--from", "catalejo[mcp]", "catalejo", "mcp"]
}
}
}That needs uv. If you'd rather pip install "catalejo[mcp]", use "command": "catalejo", "args": ["mcp"]. If Claude can't find the command, put the full path from which uvx (or which catalejo).
Claude Code: claude mcp add catalejo -- uvx --from "catalejo[mcp]" catalejo mcp
Why not just ask an AI with web search?
Because the CNMV's search pages are forms that search engines barely index. An agent with web search ends up reading press articles: incomplete, late, and you can't tell what's missing. With catalejo it reads the official register directly: each filing with its exact time, registry number and a link to the original document. And it can do what web search can't, like going through years of a company's history, and it tells you when a search came back incomplete.
Being a good citizen
catalejo talks only to cnmv.es, sends an identifiable User-Agent, makes at most one request per second and caches responses on disk (~/.cache/catalejo, or set CATALEJO_CACHE_DIR). Filed documents never change, so they are downloaded once. Please keep it that way if you fork it.
Known limitations
Price-sensitive announcements (
IP) have their own channel since 8 February 2020. Before that, everything was published as hechos relevantes, which catalejo doesn't cover yet.Searching by NIF is fast (the CNMV filters). Searching by name works, but scans every filing in the window, so keep the window short.
Times are the CNMV's registration time, to the minute.
Filings come in the language the issuer used, which is almost always Spanish.
Lists of filings are cached for up to an hour, so a filing registered a few minutes ago may not show up straight away (see Troubleshooting).
catalejo reads the CNMV's public web pages. If the CNMV changes them, parsing can break until catalejo is updated. Please open an issue if it does.
A few filings (voting rights, annual reports...) link to a CNMV page instead of a PDF.
document_text()raisesValueErrorfor those.document_text()extracts the text layer of the PDF. Scanned documents with no text layer come back empty: there's no OCR.No data of its own yet: every call reads the CNMV live (or from the cache). There's no history of when catalejo first saw a filing, only the CNMV's registration time.
Each search reads at most 50 pages (500 filings) per kind. That's about a month of OIR across all issuers, and years for a single NIF. Past that you get the newest ones and an
IncompleteResultsWarning; passstrict=True(or--strict) to get an error instead. A page that doesn't look like a CNMV result raisesCNMVParseErrorrather than coming back empty.issueris the company a filing is about, not always who filed it: a bidder's announcements about a takeover are filed under the target.securities()lists the ISINs the CNMV has active today. Deregistered ones (matured bonds, for example) don't appear, so it isn't a history.Early days: the API may still change before 1.0.
Troubleshooting
the MCP server needs an extraordocument_text() needs pypdf: install the extra,pip install "catalejo[mcp]"orpip install "catalejo[pdf]".A very recent filing is missing: delete the cache folder (
~/.cache/catalejo, or whateverCATALEJO_CACHE_DIRpoints to) and try again.A search by name is slow: it pages through every filing in the window, one request per second. Search by NIF instead, or use a shorter window.
HTTP 5xxor timeouts: the CNMV site is having trouble. catalejo already retries a few times; wait a bit and try again.Claude doesn't show the catalejo tools: check that
uvxis on yourPATH(uvx --version) and restart Claude after editing its config.
Roadmap
Price-sensitive and other regulatory announcements, with full history
ISINs per issuer, text of filed PDFs
MCP server
Command line
Directors' and managers' share dealings (art. 19 MAR)
Net short positions
Takeover bids (OPAs): status, price, spread
Fund portfolios
Contributing
Fixes and new CNMV sources are welcome. See CONTRIBUTING.md and the issues labelled good first issue.
Data and license
The data comes from the CNMV public registers and remains subject to the CNMV's legal notice: reproduce it faithfully, and if you ever sell it, tell your buyers it's free at cnmv.es. catalejo is not affiliated with or endorsed by the CNMV.
Code: MIT. See LICENSE.
Available Tools
2 toolsissuer_filingsA
Filings from one specific company at the Spanish CNMV, newest first.
issuer: its Spanish tax id / NIF ("A64907306") is best: the CNMV filters by it
directly, so even years of history come back in seconds. A company name or part
of it ("Cellnex", "telefonica") also works but scans every filing, so keep
days small (7-14) when searching by name.
since / until: optional date range (YYYY-MM-DD) for history; overrides days.
Price-sensitive announcements (IP) exist from Feb 2020 onwards.
complete is false if the search was cut short; found counts every match,
returned how many are in filings.
Inputs: issuer (required), days, kind, limit, +2 more. Returns: object
latest_filingsA
Latest filings published at the Spanish CNMV, newest first.
kind: "IP" = price-sensitive announcements, "OIR" = other regulatory announcements.
For one company, or for longer periods, use issuer_filings.
complete is false if the search was cut short; found counts every match,
returned how many are in filings. In each filing, issuer is the company
the filing is about: a bidder's announcements about a takeover, for example,
are filed under the target.
Inputs: days, kind, limit. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools are split by scope: latest_filings covers market-wide recent filings while issuer_filings targets one company, and each description explicitly points to the other for its use case. Only mild overlap remains since both return the same filing objects from the same source.
Both tools follow the same predictable '<qualifier>_filings' pattern in snake_case, making their relationship immediately readable.
Two tools is thin for a filings server; a single listing primitive plus a per-issuer variant leaves no room for filtering, document retrieval, or issuer lookup as distinct operations.
Listing coverage is reasonable (recent market-wide and per-issuer history with date ranges), but there is no way to fetch the content or attachments of an individual filing, and no issuer search/lookup tool, which are notable gaps for this domain.
Maintenance
Related MCP Connectors
Spain CNMV Regulated Filings MCP — keyless, same-day-fresh.
SEC EDGAR filings for AI agents: company lookup, filings, financials, insider trades. No keys.
SEC EDGAR filings for AI agents: company lookup, filings, financials, insider trades. No keys.
SEC filings — 13F, Form 4, 8-K, 13D, IPO and short-interest data — as 17 agent tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to download, parse, and analyze SEC EDGAR filings, including 10-K/Q reports, XBRL financial statements, and insider trading data. It provides structured access to institutional holdings, corporate events, and financial facts for comprehensive investment research.19MIT
- AlicenseAqualityBmaintenanceProvides access to SEC EDGAR financial data, enabling AI agents to fetch company filings, financial metrics, and narrative sections. It supports natural-language metric searching and extracts structured data from 10-K, 10-Q, and 8-K reports.6125 PyPIMIT
- AlicenseAqualityBmaintenanceQuery SEC EDGAR for company filings, financial data, and executive disclosures. Search by company name or ticker, retrieve 10-K/10-Q/8-K filings, and extract structured financials — backed by the official SEC EDGAR API, built for AI agents.4MIT
- FlicenseNot gradedqualityDmaintenanceProvides financial data and market filings via Streamable HTTP tools. Enables AI agents to resolve equity entities, fetch SEC filings, compare institutional holders, and export finance receipts.-