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

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:

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:

• 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

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

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

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:

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

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.

License

MIT. The data served by OpenMercantil is subject to the source-specific terms published in each response and at openmercantil.es/terminos-de-uso.

Related

• @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.