catalejo
<p align="center"><img src="https://raw.githubusercontent.com/polfananas/catalejo/main/docs/catalejo-spyglass.png" alt="catalejo: a spyglass drawn in white line art on black"></p>
# catalejo
[](https://github.com/polfananas/catalejo/actions/workflows/tests.yml)
> *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)

<!-- TODO: second GIF, Claude Desktop using the MCP server -->
```python
>>> 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
```bash
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 PDFs
```
Python 3.10+. Or try it without installing anything, with [uv](https://docs.astral.sh/uv/):
```bash
uvx catalejo filings --days 3 --kind IP
```
## Example: a takeover bid, as it happened
How BBVA's bid for Banco Sabadell started, straight from the official register, to the minute:
```bash
catalejo filings --issuer A08000143 --kind IP --since 2024-04-30 --until 2024-05-31
```
```
2024-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...
```python
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:**
```python
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:
```python
>>> [s for s in catalejo.securities("A64907306") if s.is_share]
[Security(isin='ES0105066007', fisn='CLNX/AC 0.25', cfi='ESVUFB', ...)]
```
## Command line
```bash
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:
```json
{
"mcpServers": {
"catalejo": {
"command": "uvx",
"args": ["--from", "catalejo[mcp]", "catalejo", "mcp"]
}
}
}
```
That needs [uv](https://docs.astral.sh/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](https://github.com/polfananas/catalejo/issues) if it does.
- A few filings (voting rights, annual reports...) link to a CNMV page instead of a PDF. `document_text()` raises `ValueError` for 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`; pass `strict=True` (or `--strict`) to get an error instead. A page that doesn't look like a CNMV result raises `CNMVParseError` rather than coming back empty.
- `issuer` is 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 extra`** or **`document_text() needs pypdf`**: install the extra, `pip install "catalejo[mcp]"` or `pip install "catalejo[pdf]"`.
- **A very recent filing is missing**: delete the cache folder (`~/.cache/catalejo`, or whatever `CATALEJO_CACHE_DIR` points 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 5xx` or 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 `uvx` is on your `PATH` (`uvx --version`) and restart Claude after editing its config.
## Roadmap
- [x] Price-sensitive and other regulatory announcements, with full history
- [x] ISINs per issuer, text of filed PDFs
- [x] MCP server
- [x] 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](https://github.com/polfananas/catalejo/blob/main/CONTRIBUTING.md) and the issues labelled [`good first issue`](https://github.com/polfananas/catalejo/labels/good%20first%20issue).
## Data and license
The data comes from the [CNMV](https://www.cnmv.es) public registers and remains subject to the CNMV's [legal notice](https://www.cnmv.es/Portal/utilidades/NotaLegal): 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](https://github.com/polfananas/catalejo/blob/main/LICENSE).
<!-- mcp-name: io.github.polfananas/catalejo -->
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.