@nubiia/mcp-borme
Advanced tools
MCP server for the BORME (Boletín Oficial del Registro Mercantil) through the OpenMercantil API: company search and reports, officers, daily summaries, sectors, public procurement and mercantile-law norms for AI assistants like Claude. Built by Nubiia.
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 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 — 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.
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. Tool responses keep the source attribution (
_attributions) and the tool descriptions repeat the documentary, not-legal-advice caveats.
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)
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 and
docs/api-notes.md. With 200 requests a day, the server is built to
be frugal:
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.OPENMERCANTIL_MAX_RESPONSE_CHARS (default 60,000) is replaced by a
valid-JSON envelope that says it was cut.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.37 read-only tools, all marked readOnlyHint: true — nothing in this server writes to
OpenMercantil or anywhere else.
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_companiesborme_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_sourcesborme_get_daily_summaryborme_search_persons, borme_get_person, borme_get_person_graphborme_list_sector_companies, borme_get_sector_ratios,
borme_get_cnae, borme_get_cnae_treeborme_list_legal_norms, borme_get_legal_norm,
borme_get_legal_article, borme_get_act_mapborme_search_tenders, borme_get_tender,
borme_get_tender_stats, borme_list_tender_suppliersborme_get_health, borme_get_stats, borme_get_sources_freshnessEverything 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.
npm install -g @nubiia/mcp-borme
git clone https://github.com/nubiia-dev/mcp-borme.git
cd mcp-borme
npm install
npm run build
| 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. |
export OPENMERCANTIL_API_KEY=omk_your_key # optional
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.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:
{
"mcpServers": {
"borme": {
"command": "node",
"args": ["/path/to/mcp-borme/dist/index.js"]
}
}
}
# 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
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.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.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-onlySearch 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.
{ "q": "Telefónica de España", "limit": 5 }
borme_get_company · read-onlyThe 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-onlyBORME acts of one company for a calendar year (year, default current), paginated
(page, page_size ≤ 100). Check total and pages.
{ "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_companiesStructured 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, _sourcesPublic 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-onlyWhat 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).
{ "date": "2026-07-07", "province": "Madrid", "limit": 20 }
borme_search_persons, borme_get_person, borme_get_person_graphPersons 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_treeCompanies 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_mapThe 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_suppliersPublic 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_freshnessDataset size and freshness — worth checking before asserting that something "was not published".
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.
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.
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 for the full workflow and
docs/api-notes.md for API behaviour verified against the live service.
MIT. The data served by OpenMercantil is subject to the source-specific terms published in each response and at openmercantil.es/terminos-de-uso.
@nubiia/mcp-newsapi — MCP server for the
NewsAPI.ai (Event Registry) news API.@nubiia/mcp-holded — MCP server for the
Holded invoicing/accounting API.@nubiia/mcp-signaturit — MCP server
for the Signaturit e-signature API.FAQs
MCP server for the BORME (Boletín Oficial del Registro Mercantil) through the OpenMercantil API: company search and reports, officers, daily summaries, sectors, public procurement and mercantile-law norms for AI assistants like Claude. Built by Nubiia.
We found that @nubiia/mcp-borme demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.