MCP BORME
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
429reports the plan, when to retry and how to get a larger quota. ShortRetry-Aftervalues are honoured automatically; long ones (the daily quota) are reported immediately instead of blocking.
Related MCP server: handelsregister-mcp
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_companiesOther 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_sourcesDaily bulletin (1):
borme_get_daily_summaryPersons (3):
borme_search_persons,borme_get_person,borme_get_person_graphSectors / CNAE (4):
borme_list_sector_companies,borme_get_sector_ratios,borme_get_cnae,borme_get_cnae_treeMercantile law (4):
borme_list_legal_norms,borme_get_legal_norm,borme_get_legal_article,borme_get_act_mapPublic procurement (4):
borme_search_tenders,borme_get_tender,borme_get_tender_stats,borme_list_tender_suppliersService (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-bormeInstall from source
git clone https://github.com/nubiia-dev/mcp-borme.git
cd mcp-borme
npm install
npm run buildConfiguration
Environment Variables
Variable | Required | Description |
| No | OpenMercantil API key ( |
| No | Local cap on requests per minute across all tools. Default 60 (the anonymous limit); raise it with a paid plan. |
| No | Maximum size of one tool response. Default 60000; larger results are cut with a notice. |
| No | Override the API host (mirrors, local mocks). |
export OPENMERCANTIL_API_KEY=omk_your_key # optionalClaude 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@latestTroubleshooting
sh: mcp-borme: command not foundwhen launching from inside this repo. If you start Claude Code (or another MCP client) from the cloned repository directory,npx @nubiia/mcp-bormeresolves the localpackage.jsoninstead of the published package, and themcp-bormebinary is not on thePATH. 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_unavailableon 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 |
|
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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Find who is behind any Spanish company: directors, public contracts, grants and official sources.
Verify Spanish companies by CIF: registry data, status and BORME filings, paid per call over x402.
CompanyLens is a remote MCP server giving AI agents instant access to official company registry data across 19 jurisdictions in Europe, the Americas, and Asia-Pacific. Eighteen read-only tools let you search companies and people, look up officers and beneficial owners, map corporate networks through shared directors, screen names against the UK disqualified directors register, find every company at a registered address, and pull filing history — all from a single connector. Visit our website: https://companylens.io
Data and tools for your AI agent: company, people, SEO, social and EU register data. Pay per call.
Related MCP Servers
- AlicenseAqualityCmaintenanceStructured business intelligence for AI agents. 11.3M verified entities, 40.3M BORME mercantile acts, EU VAT validation (VIES), GLEIF LEI and healthcare registries. 12 tools.61MIT
- AlicenseAqualityDmaintenanceEnables AI agents to search and retrieve structured data from the German Commercial Register, including company details, filed documents, and shareholder lists.75Apache 2.0
- AlicenseAqualityDmaintenanceEnables AI assistants to search and retrieve UK Companies House data including company profiles, officers, and filing history via the official API.4199 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to perform due diligence, KYB, and supplier or client verification by querying Spanish company registry data cross-referenced with public grants and procurement awards, each fact linking to its official publication.MIT