BORME API

com.bormeapiPublished by bormeapi.comOfficial publisherv2.1.0Updated Oct 30, 2026

Spain's company registry gazette (BORME): more than 9.6 million events since 2009. API key or OAuth.

VerifiedStreamable HTTPWeb executableFinanceBusiness & Commerce

Overview

AI-generated overview

Hosted MCP server for Spain's BORME company registry gazette, letting an assistant search 9.6M+ registry events, company histories, NIF lookups and trademarks.

What you can do
  • Search and read registry events by date, province, act type or company name, plus daily digests and act-type lists
  • Find companies by name or NIF/CIF and pull one company's published timeline
  • Look up trademarks and trading names, and which company a brand belongs to
  • Check recent risk signals and the size and freshness of the underlying data
When to use it
Useful when an assistant needs Spanish commercial-registry facts: insolvency notices, board changes, incorporations, company identification by name or tax ID, or brand-to-company links. It suits due-diligence, research and monitoring questions about Spanish companies.
Requirements
Remote Streamable HTTP endpoint; nothing to install. Either an API key sent in the X-API-Key header, or OAuth sign-in with a BORME API account. Without a key the free plan applies (50 requests a day, last 7 days of events). Some tools need Basic, Pro or Risk plans. A local stdio variant needs Python 3.12 or Docker and BORME_API_KEY.
Before you install
The X-API-Key header is a secret; keep it out of shared configs. Each tool call counts against the daily quota shared with the REST API. Deeper history, NIF lookup, trademarks and risk signals require paid plans. Trademark and NIF associations are data matches, not legal confirmation, and missing results are not proof of absence.

Installation

In SourceWeft

  1. Open BORME API in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/com.bormeapi%2Fborme-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "borme-api": {
      "type": "http",
      "url": "https://mcp.bormeapi.com/mcp"
    }
  }
}

README

BORME API MCP connector

[MCP Badge] [SealKeeper Service SEAL]

Español: README.es.md

Connect Microsoft Copilot, Claude, ChatGPT, Cursor, VS Code or any MCP client to the hosted BORME API MCP server: Spanish commercial-registry data published in the BORME (Boletín Oficial del Registro Mercantil), with more than 9.6 million events since 2009, company histories, company search by name, NIF lookup, trademarks and trading names, and risk signals.

The server is hosted at mcp.bormeapi.com; there is nothing to install or run, and it is the recommended way to connect. This repository holds what you need around it: connection settings for each client, an agent skill, the event-type vocabulary, and a local stdio server that wraps the BORME API REST endpoints, for clients that only start servers over stdio.

The full guide, kept up to date, is at bormeapi.com/mcp. If this README and that page ever disagree, the page is right.

Two ways to connect

API key: https://mcp.bormeapi.com/mcp

  • Transport: Streamable HTTP. Each request gets a plain JSON response; no session is kept between calls.
  • Authentication: your API key in the X-API-Key header. Without a key, the free plan's limits apply.
  • For clients that can send a header: Microsoft Copilot Studio, Claude Code, Cursor, VS Code, Claude Desktop (through mcp-remote) and any other Streamable HTTP client.

OAuth: https://mcp.bormeapi.com/mcp/oauth

  • For assistants with custom connectors that sign in with OAuth, such as Claude.ai, ChatGPT or Copilot. There is no API key to paste anywhere: you sign in with your BORME API account, and the app uses the plan of the account that authorized it.
  • This endpoint requires a BORME API account and ignores the X-API-Key header. Its calls share your API key's daily quota with REST API and /mcp calls made with that key.
  • If your account has no active API key, the tools return an error directing you to your account page; they work again once your account has an active key, without reconnecting the app.
  • If the app does not use the connection for 30 days, connect it again. You can disconnect the app at any time under Connected apps on your account page.
  • For client developers: an unauthenticated call gets 401 with WWW-Authenticate: Bearer resource_metadata="https://mcp.bormeapi.com/.well-known/oauth-protected-resource/mcp/oauth". The authorization server is https://bormeapi.com (metadata at /.well-known/oauth-authorization-server), with dynamic client registration, PKCE (S256) and the scope mcp.

Get an API key on your account page.

Set up your client

Claude.ai (OAuth)

  1. Go to Customize > Connectors > Add custom connector.
  2. Enter https://mcp.bormeapi.com/mcp/oauth as the server URL. Claude detects how to sign in and shows Sign in now and Register automatically; keep these options.
  3. Click Add. Our sign-in page opens.
  4. Sign in with the link we email you, then select Allow.
  5. Back in Claude, if the connector page says the connector has no tools, reload the page.

On Team and Enterprise plans an owner adds the connector under Organization settings.

To use your API key instead, enter https://mcp.bormeapi.com/mcp, choose No sign-in and add the x-api-key header with your key under Request headers. Anthropic offers request headers as a beta to a limited set of organizations; if you do not see that section, use the Claude Desktop setup below.

ChatGPT (OAuth)

ChatGPT's custom connectors cannot send an API-key header. Add a custom connector with https://mcp.bormeapi.com/mcp/oauth as the server URL and sign in with your BORME API account. The screens and their names may differ from Claude.ai's. Without OAuth, ChatGPT can use https://mcp.bormeapi.com/mcp only without a key, on the free plan.

Microsoft Copilot Studio and Microsoft 365 Copilot (API key)

These steps follow Microsoft's documentation. They may vary with your tenant and your data loss prevention (DLP) policies.

  1. In Copilot Studio, open the agent you want to use and go to Tools > Add a tool > New tool > Model Context Protocol.
  2. Enter a Server name (BORME API), a Server description and the Server URL: https://mcp.bormeapi.com/mcp
  3. For authentication, choose API key, set Type to Header and enter X-API-Key as the header name. Select Create, then Create a new connection, enter your key and select Add to agent.
  4. Test the agent in Copilot Studio first. Then publish it and set up the Teams and Microsoft 365 Copilot channel, subject to your organization's permissions and policies. If your organization has Power Platform data policies (DLP), an administrator may need to allow this connector.

Claude Code (API key)

bash
claude mcp add --transport http --scope user \  --header "X-API-Key: YOUR_KEY" \  borme https://mcp.bormeapi.com/mcp

--scope user makes the server available in all your projects; leave it out to add it to the current project only.

Cursor (API key)

Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project) and set BORME_API_KEY in your environment:

json
{  "mcpServers": {    "borme": {      "url": "https://mcp.bormeapi.com/mcp",      "headers": { "X-API-Key": "${env:BORME_API_KEY}" }    }  }}

VS Code (API key)

Add this to .vscode/mcp.json in your workspace. VS Code asks for the key the first time the server starts:

json
{  "inputs": [    {      "type": "promptString",      "id": "borme-api-key",      "description": "BORME API key",      "password": true    }  ],  "servers": {    "borme": {      "type": "http",      "url": "https://mcp.bormeapi.com/mcp",      "headers": { "X-API-Key": "${input:borme-api-key}" }    }  }}

Claude Desktop (API key)

Add the server to claude_desktop_config.json through mcp-remote, a third-party bridge that needs Node.js:

json
{  "mcpServers": {    "borme": {      "command": "npx",      "args": ["mcp-remote", "https://mcp.bormeapi.com/mcp",               "--header", "X-API-Key:${BORME_API_KEY}"],      "env": { "BORME_API_KEY": "YOUR_KEY" }    }  }}

Any other Streamable HTTP client (API key)

Send each JSON-RPC message as a POST to https://mcp.bormeapi.com/mcp with Content-Type: application/json, an Accept header that includes application/json, and your key in X-API-Key. For example, to list the tools:

bash
curl -s https://mcp.bormeapi.com/mcp \  -H "Content-Type: application/json" \  -H "Accept: application/json, text/event-stream" \  -H "X-API-Key: YOUR_KEY" \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Local stdio server

server.py is a local stdio server that wraps the BORME API REST endpoints; the hosted server at mcp.bormeapi.com is the recommended way. It offers the same tools, with the same names, titles, descriptions, parameters and annotations (all tools are read-only), as the hosted server: they are copied into tools.json. Each tool call makes one or more requests to https://api.bormeapi.com/v1/.... It holds no data; MCP directories build an image from its Dockerfile to list the tools.

  • Listing the tools needs no key and no network.
  • Calling a tool needs an API key for every tool except list_act_types and registry_stats: the REST API, unlike the hosted MCP server, has no keyless free plan. Your free key is in your account. Set it as BORME_API_KEY.
  • daily_digest and registry_stats return fewer fields than on the hosted server, because the REST API has no single endpoint for them: daily_digest returns the day's event count, its parse completeness and up to 200 insolvency notices, and registry_stats returns the latest publication date and, with a key, the parse completeness of the last 30 publication days.
  • It does not sign in with OAuth.

With Docker:

bash
docker build -t borme-mcp .docker run -i --rm -e BORME_API_KEY=YOUR_KEY borme-mcp

With Python 3.12:

bash
pip install -r requirements.txtBORME_API_KEY=YOUR_KEY python server.py

When the hosted server changes its tools, run python scripts/update_tools.py to regenerate tools.json and commit it. CI fails while tools.json and the hosted server differ.

Tools

  • search_companies - find companies by current or former name and get ranked company cards.
  • company_history - the registry timeline of one company: the published acts available under your plan, newest first.
  • search_events - search BORME notices by date, province, act type and company name.
  • daily_digest - one publication day in figures, with its insolvency notices.
  • company_by_nif - find a company by its NIF/CIF tax ID (Basic plan and above).
  • brand_owner - find the company a trademark or trading name is linked to (Basic plan and above).
  • company_brands - trademarks and trading names linked to one company (Basic plan and above).
  • recent_signals - the latest risk signals, such as insolvency filings and mass exits (Risk plan).
  • list_act_types - the act types, with their English labels and the original Spanish headings.
  • registry_stats - size and coverage of the registry data.
  • company_snapshot - a company profile with officers, sole shareholder and capital (Basic plan and above).
  • company_signals - one company's derived signals, with date and type filters (Pro plan and above).
  • act_stats - act counts by type, period and province, including mergers, spin-offs and capital increases (Pro plan and above).

Each tool's description and parameter schema, as returned by tools/list, explain its parameters.

Prompts and resources

Besides tools, the hosted server and the local stdio server offer prompts, ready-made instructions that your client can offer you (in Claude, from the + menu; in other clients, wherever they list a server's prompts), and resources, reference data that your client can attach as context. A prompt only supplies the instructions: the tool calls it leads to count against your plan as usual.

  • company_due_diligence (company): a report on one company's identification, published history, officer appointments and insolvency notices, citing the BORME id of each act.
  • board_changes (company, since): appointments, re-elections, terminations and resignations, revocations and ex officio cancellations of appointments, optionally since a date.
  • new_companies_digest (province, date): companies whose incorporation notices were published in BORME on one day, for one province or autonomous community. If date is omitted, it uses the latest publication day.
  • check_nif (nif): which company a NIF/CIF is linked to in our data, and its latest published acts (Basic plan and above).
  • visit_briefing (company): a briefing for a client visit, with a company profile and its history and signals from the last 24 months.

The prompts tell the model to cite BORME ids, to tell a name match from a confirmed identification or ownership, and not to treat a missing result as proof that something does not exist.

  • borme://act-types: the act types, as list_act_types returns them.
  • borme://provinces: the provinces and autonomous communities that the province filters accept. It needs BORME_API_KEY; without a key, reading the resource returns instructions for obtaining a free API key.
  • borme://coverage: data freshness, as registry_stats returns it on this server.

One resource template takes a company slug:

  • borme://company/{slug}: up to 20 of the most recent published events of one company, by slug (for example borme://company/vaz-metales-sl), as company_history returns them with limit 20 and order desc, under the same plan rules. On the hosted server without an API key, only events from the last 7 days are visible; the local server requires BORME_API_KEY. For more events, call company_history.

Plans and limits

  • No key or free key: 50 requests a day, events from the last 7 days, company search by name (first 5 results), company histories and daily digests within those 7 days, the act-type list and registry statistics.
  • Basic: 5,000 requests a day, 365 days of history, NIF lookup, the NIF on company search results, trademarks and trading names.
  • Pro: 50,000 requests a day and the full history since 2009.
  • Risk: 200,000 requests a day and the risk signals tool.

The MCP server uses the same key and the same daily quota as the REST API. Each tool call counts as one request against the daily quota of your key (or, without a key, of your IP address). Results are capped per call (for example, 200 events); page with offset where a tool offers it.

Plans and prices: bormeapi.com/#pricing.

Data

  • More than 9.6 million events since 2009 from BORME-A (acts registered in the Registro Mercantil), updated every publication day.
  • Results are based on published BORME notices and other public data. Associations involving trademarks or NIFs are data matches and do not constitute legal confirmation.
  • Not included: annual accounts, BORME-C notices (legal announcements), and notices published before 2009.

In this repository

  • skills/borme-registry - an Agent Skill that tells the agent which tool to call, how to chain them and how to report the answers. skills/borme-registry-es is the same skill in Spanish. Install one of the two, not both. For Claude Code:

    bash
    git clone https://github.com/bormeapi/borme-mcp.gitmkdir -p ~/.claude/skills && cp -r borme-mcp/skills/borme-registry ~/.claude/skills/

    The skill needs the MCP server to be connected.

  • vocab/ - the act-type vocabulary: each enum with its Spanish heading and English label.

  • server.py, prompts.py, tools.json and the Dockerfile - the local stdio server described above, with its prompts, resources and resource template; scripts/update_tools.py regenerates tools.json from the hosted server.

Related

License

The contents of this repository are under the MIT License.

The data served by BORME API contains public-sector information from the Agencia Estatal Boletín Oficial del Estado (BORME), reused under Law 18/2015 and RD 1495/2011. Not affiliated with or endorsed by BOE.

Source: README.md at commit 860cc76

Tools

10

search_events

Search registry events

Search BORME registry events (since 2009) across companies by publication date, province, act type and company name, newest first. Use it for questions about many companies ("insolvency notices in Valencia in September"). For one known company use company_history; to find a company use search_companies; for one day's totals use daily_digest. Returns JSON {count, events: [{event_id, date, borme_id, province, company_name, company_slug, acts: [{act_type, act_type_raw, roles, payload}], registral}]}, plus company_name_match, plan_window and hidden_by_plan when they apply. No next page: when count equals limit, narrow the filters. Read-only; one request per call against your daily quota. Without an API key (X-API-Key header, https://bormeapi.com/account) only the last 7 days are searched (plan_window). An empty page with hidden_by_plan means matches exist outside your plan's window: do not say none exist. A bad date, province or act type is refused with a message naming the fix.

Parameterslimitdate_toact_typesdate_fromprovincescompany_name_contains

company_history

Company registry timeline

Get one company's BORME timeline: its published registry events within your plan's window. Use it once the company is known (a slug from search_companies or company_by_nif); across many companies use search_events. A name instead of a slug is searched: several matches return {ambiguous: true, candidates}, none returns {error}. Returns JSON {company_slug, total_events, first_seen, last_seen, truncated, next_offset, count, events} (as in search_events), with former_slugs for a merged company (an old slug returns the merged timeline) and plan_window on a limited plan. total_events, first_seen and last_seen cover the whole timeline in your window, not just this page. To page, keep limit and order and pass next_offset as offset (at most 10000) until it is null. Read-only; one request per call. Without an API key (X-API-Key header) only the last 7 days; basic covers 365 days, pro and risk the full history back to 2009. If all its events are outside your window, the refusal counts them.

Parameterslimitorderoffsetcompanyrequired

company_by_nif

Find a company by NIF

Look up a Spanish company by its NIF/CIF tax ID. Use it when the user gives a tax ID (with a name use search_companies); on a hit, call company_history with the company_slug. Returns JSON {found, company_slug, company_name, current_name, status, province, nif_source, nif_caveat, ...}; use current_name. BORME has no dedicated tax-ID field: there are more than 580,000 NIF mappings from public sources and the text of BORME notices, covering a minority of companies, so a miss (reason nif_unmapped) means "not matched yet", not "does not exist". invalid_input true: not a NIF/CIF. reason nif_check_character_failed: wrong check character; relay tell_the_user and the did_you_mean candidates. reason not_registry_entity: explain entity_type as the note does. ambiguous true: ask which candidate. nif_caveat present: say the link is not settled. Read-only; one request per call. Needs the basic plan or higher: send your API key in the X-API-Key header (https://bormeapi.com/account).

Parametersnifrequired

brand_owner

Find a brand's company

Find the Spanish company a trademark or trading name is linked to, in the Spanish patent office's (OEPM) trademark and commercial-name records we hold (the archive starts in 1987). Use it when the user names a brand; for a company's own name use search_companies, for a known company's brands use company_brands. Returns JSON {found, brand, matches: [{brand, kind, company_slug, company_name, company_status, file}], truncated, source, note}. kind commercial_name identifies a business; trademark distinguishes goods or services (NESCAFÉ is not another name for Nestlé): say which kind a hit is. Links come from holder-name matching (the office publishes no tax IDs); ambiguous holders stay unlinked: present a hit as a name match, not confirmed ownership. found false is not proof the brand is unused. On a hit, use company_history with the slug. Read-only; one request per call. Needs the basic plan or higher: send your API key in the X-API-Key header (https://bormeapi.com/account).

Parametersbrandrequiredlimit

company_brands

A company's brands

List the trademarks and trading names that the Spanish patent office (OEPM) records under a holder with this company's name. Use it for a known company (a slug from search_companies or company_history); to go from a brand to its company use brand_owner. Returns JSON {company_slug, commercial_names, trademarks (each {name, file, status, since}), counts, truncated, limit_per_kind, source, note}. The office publishes no tax IDs, so every link is a name match, not confirmed ownership. An empty result means none is linked in our data, not that the company holds none. limit applies to each kind separately, newest first; counts is what this answer lists, not the company's total, and truncated true for a kind means more are linked: raise limit. Read-only; one request per call. Needs the basic plan or higher: send your API key in the X-API-Key header (https://bormeapi.com/account).

Parameterslimitcompanyrequired

recent_signals

Recent risk signals

Get a sample of the latest risk signals derived from BORME and public sources: at most 10 rows dated within the last 7 days. Use it for "what risk signals appeared this week"; not a per-company check (use company_history) and not the full feed (the hosted API's /v1/signals). Returns JSON {count, window, sample_cap, signals: [{signal_type, date, company_slug, company_name, province, details}], full_feed}. AEAT_DEBTOR comes from the AEAT's yearly debtors list (art. 95 bis LGT): details carry listed_on, list_year, is_current_list (true for 12 months from listed_on) and debt_eur, the published total at 31 December of the prior year. Say the company was on the list published on that date; never say the debt is still outstanding. count 0 means none in the window, not that a company is risk-free; an unknown signal_type is refused with the valid list. Read-only; one request per call. Needs the risk plan: send your API key in the X-API-Key header (https://bormeapi.com/account).

Parameterssignal_type

daily_digest

Daily BORME digest

Summarise one BORME publication day: total events, counts by act type, the top 10 provinces and the day's insolvency-proceedings notices. Use it for "what was published today" or a day's figures; to read the notices use search_events with date_from = date_to = that day. Returns JSON {date, total_events, by_type, top_provinces, insolvencies: [{company, province}]}. insolvencies lists the events with INSOLVENCY_DECLARATION or INSOLVENCY_STATUS (not SUSPENSION_OF_PAYMENTS, BANKRUPTCY_LEGACY or PROVISIONAL_SHEET_CLOSURE_INSOLVENCY). An INSOLVENCY_STATUS notice can record any stage, from a request for a declaration to the conclusion: before saying a company was declared insolvent, read the act's payload with search_events. A day without a gazette (weekends, holidays) returns total_events 0. Read-only; one request per call. Without an API key only days within the last 7 days; send your key in the X-API-Key header (https://bormeapi.com/account) for your plan's window.

Parametersdate

search_companies

Search companies by name

Find Spanish companies by name and return ranked company cards. Use it first when the user gives a company name, then company_history with its company_slug; with a tax ID use company_by_nif, with a brand use brand_owner. Matches current names, former names and variants, ignoring accents, case, punctuation and the legal form. Returns JSON {query, count, total, total_is_at_least, truncated, limit, offset, companies: [{company_slug, name, legal_form, province, municipality, status, in_insolvency, last_act_date, match, matched_on}]}. match is exact, prefix, contains or fuzzy (a lead, not an identification; say so). Ranked by match, then active companies, then newest act. Read-only; one request per call; not limited by the free plan's 7 days of history. The free plan shows at most the first 5 ranked cards; hidden_by_plan counts the rest: relay its note. The NIF is on the card from the basic plan up (X-API-Key header). An empty answer is not proof that a business does not exist.

Parametersnamerequiredlimitoffsetstatusprovince

list_act_types

List act types

List every normalized BORME act type: the enum used by the act_types filter of search_events (act_type), its Spanish label (spanish) and its English label (english). Use it to choose act_types values or to translate act types in an answer; it reads no registry data. Returns a JSON array of {act_type, spanish, english}, sorted by act_type. Read-only, open to everyone, no key needed and not counted against a quota. The same list is the resource borme://act-types.

Takes no parameters.

registry_stats

Data coverage and freshness

Report the coverage and freshness of the BORME data behind this server. Use it to answer "how much data is there?", "how fresh is it?" and "can I trust date filters for period X?" before running searches; it says nothing about any one company. Returns JSON {events_approx, companies_approx, coverage: {from, to}, parse_completeness_last_30d, source}: approximate event and company counts (planner estimates, not exact tallies), the first and latest publication day held (YYYY-MM-DD), and the event-weighted parse completeness over the 30 days up to the latest run (e.g. 0.9987). Takes no arguments. Read-only, open to everyone, no key needed and not counted against a quota. The same report is the resource borme://coverage.

Takes no parameters.

Version history

2
  1. v2.1.0LatestOct 30, 2026
  2. v1.2.0Oct 29, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts