MCP BORME
by nubiia-dev
README.md
# MCP BORME
[](https://github.com/nubiia-dev/mcp-borme/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@nubiia/mcp-borme)
[](https://opensource.org/licenses/MIT)
[](https://nubiia.es)
A Model Context Protocol (MCP) server for the **BORME** (*Boletín Oficial del Registro
Mercantil*, Spain's commercial-registry bulletin), built on the public
[OpenMercantil](https://openmercantil.es) API. It lets AI assistants like Claude search
Spanish companies, read their registry history and officers, browse the daily bulletin,
map sectors by CNAE, look at public procurement and consult the mercantile-law norms behind
each registry act.
> Built and maintained by **[Nubiia](https://nubiia.es)** — automatización e
> integraciones con IA para negocios (MCP, Holded, Pipedrive y más). ¿Quieres algo así
> para tu empresa? Escríbenos en **[nubiia.es](https://nubiia.es)**.
> **Independent and informational.** OpenMercantil is not the BOE, the BORME or the
> Registro Mercantil, and its data does **not** replace official certificates or registry
> extracts. BORME material is re-used under Ley 37/2007; the official version is on
> [boe.es](https://www.boe.es/diario_borme/). Tool responses keep the source attribution
> (`_attributions`) and the tool descriptions repeat the documentary, not-legal-advice caveats.
## No account needed
The OpenMercantil API is **public**: this server works out of the box on its anonymous free
tier (**60 requests/minute and 200 requests/day per IP**). An optional API key
(`OPENMERCANTIL_API_KEY`, `omk_...`, from [openmercantil.es](https://openmercantil.es))
selects your account's larger quota:
| Plan | Per minute | Per day |
|---|---|---|
| Free (anonymous, per IP) | 60 | 200 |
| Profesional (API key) | 120 | 5,000 |
| MAX (API key) | 600 | 50,000 |
| Enterprise (contract) | 1,200 | 500,000+ |
Plans change — see [openmercantil.es](https://openmercantil.es) and
[`docs/api-notes.md`](docs/api-notes.md). With 200 requests a day, the server is built to
be frugal:
- Every input is **validated locally** against the OpenAPI bounds, so a bad call never
costs a request.
- Result counts default to small numbers (10 results, 10 events, 10 acts per province) and
big payloads are **trimmed with an explicit notice** (`events_total`, `events_truncated`,
`total_acts`...) so the assistant knows what it did not see and which tool pages the rest.
A full company report (~60 KB) arrives as ~6 KB; a full day of the bulletin (~340 KB) as
a per-province summary.
- Any response above `OPENMERCANTIL_MAX_RESPONSE_CHARS` (default 60,000) is replaced by a
valid-JSON envelope that says it was cut.
- Responses carry the API's rate-limit state; a `429` reports the plan, when to retry and
how to get a larger quota. Short `Retry-After` values are honoured automatically; long
ones (the daily quota) are reported immediately instead of blocking.
## Features
37 read-only tools, all marked `readOnlyHint: true` — nothing in this server writes to
OpenMercantil or anywhere else.
- **Companies** (11): `borme_search_companies`, `borme_get_company`,
`borme_compare_companies`, `borme_get_company_events`, `borme_get_company_facts`,
`borme_get_company_timeline`, `borme_get_company_officers`,
`borme_get_company_relationships`, `borme_get_company_graph`,
`borme_get_company_activity`, `borme_get_similar_companies`
- **Other public sources per company** (7): `borme_get_company_contracts`,
`borme_get_company_grants`, `borme_get_company_ted`, `borme_get_company_cnmv`,
`borme_get_company_wikidata`, `borme_get_company_bde`, `borme_get_company_sources`
- **Daily bulletin** (1): `borme_get_daily_summary`
- **Persons** (3): `borme_search_persons`, `borme_get_person`, `borme_get_person_graph`
- **Sectors / CNAE** (4): `borme_list_sector_companies`, `borme_get_sector_ratios`,
`borme_get_cnae`, `borme_get_cnae_tree`
- **Mercantile law** (4): `borme_list_legal_norms`, `borme_get_legal_norm`,
`borme_get_legal_article`, `borme_get_act_map`
- **Public procurement** (4): `borme_search_tenders`, `borme_get_tender`,
`borme_get_tender_stats`, `borme_list_tender_suppliers`
- **Service** (3): `borme_get_health`, `borme_get_stats`, `borme_get_sources_freshness`
### Deliberately out of scope
Everything that is not part of OpenMercantil's public read plane: user accounts, lists,
notes, segments, API-credential and webhook management, billing, support tickets and the
legal-report purchase flow (all of them write data or need a browser session). Also left
out: the bulk `export/*` and CSV downloads, the legacy aliases, the aggregate dashboards
(`ccaa/stats`, `sectores/stats`, `datasets/public`, `integrations`) and the per-company
risk-signal endpoints (sanctions, embargoes, AEAT debtors, score), which are not part of
the allowlisted credential scopes of the public API.
## Installation
### Prerequisites
- Node.js 22.14 or higher
- Optionally, an OpenMercantil API key from **[openmercantil.es](https://openmercantil.es)**
### Install from npm
```bash
npm install -g @nubiia/mcp-borme
```
### Install from source
```bash
git clone https://github.com/nubiia-dev/mcp-borme.git
cd mcp-borme
npm install
npm run build
```
## Configuration
### Environment Variables
| Variable | Required | Description |
|---|---|---|
| `OPENMERCANTIL_API_KEY` | No | OpenMercantil API key (`omk_...`). Secret — never commit it. Without it the anonymous free tier is used. Sent in the `X-API-Key` header, never in a URL, and redacted from error messages. |
| `OPENMERCANTIL_MAX_REQUESTS_PER_MINUTE` | No | Local cap on requests per minute across all tools. Default **60** (the anonymous limit); raise it with a paid plan. |
| `OPENMERCANTIL_MAX_RESPONSE_CHARS` | No | Maximum size of one tool response. Default **60000**; larger results are cut with a notice. |
| `OPENMERCANTIL_BASE_URL` | No | Override the API host (mirrors, local mocks). `https` only, except `http://localhost`. |
```bash
export OPENMERCANTIL_API_KEY=omk_your_key # optional
```
### Claude Desktop Configuration
Add to your Claude Desktop config file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"borme": {
"command": "npx",
"args": ["-y", "@nubiia/mcp-borme@latest"],
"env": {
"OPENMERCANTIL_API_KEY": "omk_your_key"
}
}
}
}
```
Without a key, drop the `env` block entirely. Or if installed from source:
```json
{
"mcpServers": {
"borme": {
"command": "node",
"args": ["/path/to/mcp-borme/dist/index.js"]
}
}
}
```
### Claude Code Configuration
```bash
# anonymous free tier
claude mcp add borme -- npx -y @nubiia/mcp-borme@latest
# with an API key
claude mcp add borme --env OPENMERCANTIL_API_KEY=omk_your_key -- npx -y @nubiia/mcp-borme@latest
```
### Troubleshooting
- **`sh: mcp-borme: command not found` when launching from inside this repo.** If you
start Claude Code (or another MCP client) from the cloned repository directory,
`npx @nubiia/mcp-borme` resolves the local `package.json` instead of the published
package, and the `mcp-borme` binary is not on the `PATH`. Pin the registry version
with `@latest` (as in the examples above), or launch the client from another directory.
- **A recent date or company seems to be missing.** The OpenMercantil dataset is rebuilt
periodically and can lag behind the official bulletin. Call `borme_get_health`
(`latest_borme_processed`, `status`) to see how fresh it is.
- **`503 projection_unavailable` on grants / TED / CNMV / Wikidata / sources.** Those
tools read an integrations projection that OpenMercantil can take offline; it is a
server-side state, not evidence that the company has no such records.
## Tools
The recommended flow: **`borme_search_companies` → `borme_get_company` → detail tools.**
Company tools take the `slug` returned by the search (e.g. `telefonica-de-espana-sa`).
### `borme_search_companies` · read-only
Search by name prefix, alias or exact CIF. Returns slug, CIF, province, CNAE, share capital
(cents), first/last BORME appearance and number of acts. DNI/NIE never match.
```json
{ "q": "Telefónica de España", "limit": 5 }
```
### `borme_get_company` · read-only
The full BORME report: identity, KPIs, activity timeline, top event types, the most recent
events (`events_limit`, default 10; the response reports `events_total`) and current and
historical officers. Page the whole history with `borme_get_company_events`.
### `borme_get_company_events` · read-only
BORME acts of one company for a calendar year (`year`, default current), paginated
(`page`, `page_size` ≤ 100). Check `total` and `pages`.
```json
{ "slug": "telefonica-de-espana-sa", "year": 2025, "page_size": 20 }
```
### `borme_get_company_facts`, `borme_get_company_timeline`, `borme_get_company_officers`, `borme_get_company_relationships`, `borme_get_company_graph`, `borme_get_company_activity`, `borme_get_similar_companies`, `borme_compare_companies`
Structured facts per act type, a unified registry + procurement timeline, officers,
documentary relationships (filter by `type` / `confidence`), group graph, monthly activity
series, peers in the same province and CNAE division, and a two-company comparison. All
documentary: a mention is not proof of current status.
### `borme_get_company_contracts`, `_grants`, `_ted`, `_cnmv`, `_wikidata`, `_bde`, `_sources`
Public procurement (PLACSP), subsidies (BDNS), EU tenders (TED), stock-market listing
(CNMV), Wikidata identifiers, Banco de España sector ratios and the coverage map of those
sources. An empty result is not proof of absence.
### `borme_get_daily_summary` · read-only
What the BORME published on a date, by section and province. Because a day can hold
thousands of acts, the response gives **exact counts** plus the first `limit` acts per
province (default 10). Narrow with `province` / `section` (`"1"` registered acts, `"2"`
announcements). No bulletin is published on Sundays or holidays (404).
```json
{ "date": "2026-07-07", "province": "Madrid", "limit": 20 }
```
### `borme_search_persons`, `borme_get_person`, `borme_get_person_graph`
Persons appear **only as documentary name mentions** (usually officers). Homonyms share a
slug, identity is never resolved, and no DNI, address or contact data is exposed.
### `borme_list_sector_companies`, `borme_get_sector_ratios`, `borme_get_cnae`, `borme_get_cnae_tree`
Companies of a CNAE sector (optionally by province), Banco de España aggregate ratios per
two-digit division, code metadata and the code hierarchy.
### `borme_list_legal_norms`, `borme_get_legal_norm`, `borme_get_legal_article`, `borme_get_act_map`
The consolidated mercantile-law norms (BOE texts) and the bridge from each BORME act type to
the law that governs it. Informational only, not legal advice.
### `borme_search_tenders`, `borme_get_tender`, `borme_get_tender_stats`, `borme_list_tender_suppliers`
Public procurement notices with CPV / phase / province / buyer / supplier / amount / date
filters and cursor pagination. The API rejects some filter combinations (free text with
structured filters, `cpv` with anything but dates) with a `422` that is surfaced as-is.
### `borme_get_health`, `borme_get_stats`, `borme_get_sources_freshness`
Dataset size and **freshness** — worth checking before asserting that something "was not
published".
## Rate limiting
A local guard stops runaway agent loops before they burn the daily quota:
| Scope | Limit |
|---|---|
| All tools together | `OPENMERCANTIL_MAX_REQUESTS_PER_MINUTE` (default 60/min) |
| Each tool | 30 req/min |
`429`/`502`/`503`/`504` responses and connection-refused/DNS errors are retried with
backoff (3 attempts); timeouts and connection resets are not, to avoid wasting quota. Each
attempt times out after 30 seconds.
## Error messages
Errors say what to do: a `429` includes the plan, the retry time and the anonymous limits;
`401`/`403` point to `OPENMERCANTIL_API_KEY`; a `404` on a company or person explains that
OpenMercantil never confirms withheld or personal identities. The API key is redacted from
every error message.
## Development
```bash
npm install
npm run build
npm test # runs entirely against mocks — no network, no API key
npm run test:coverage
npm run lint
node scripts/smoke.mjs # live smoke test against the real API (about 10 requests)
```
See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full workflow and
[`docs/api-notes.md`](docs/api-notes.md) for API behaviour verified against the live service.
## License
[MIT](LICENSE). The data served by OpenMercantil is subject to the source-specific terms
published in each response and at [openmercantil.es/terminos-de-uso](https://openmercantil.es/terminos-de-uso).
## Related
- [`@nubiia/mcp-newsapi`](https://github.com/nubiia-dev/mcp-newsapi) — MCP server for the
NewsAPI.ai (Event Registry) news API.
- [`@nubiia/mcp-holded`](https://github.com/nubiia-dev/mcp-holded) — MCP server for the
Holded invoicing/accounting API.
- [`@nubiia/mcp-signaturit`](https://github.com/nubiia-dev/mcp-signaturit) — MCP server
for the Signaturit e-signature API.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues