MCP Borme

MCP BORME

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](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. 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) selects your account's larger quota:

Plans change — see openmercantil.es and 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

npm install -g @nubiia/mcp-borme

Install from source

git clone https://github.com/nubiia-dev/mcp-borme.git

cd mcp-borme npm install npm run build

Configuration

Environment Variables

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

{

"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"] } } }

Claude Code Configuration

# 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.

{ "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.

{ "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).

{ "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:

429/502/503/504 responses