apiempresas-mcp 1.4.0 → 1.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +115 -91
  2. package/dist/index.js +4 -4
  3. package/package.json +70 -48
package/README.md CHANGED
@@ -1,91 +1,115 @@
1
- # APIEmpresas MCP
2
-
3
- Servidor [MCP](https://modelcontextprotocol.io) oficial de [APIEmpresas.es](https://apiempresas.es): datos de empresas españolas para Claude, Cursor, VS Code y cualquier asistente compatible con MCP.
4
-
5
- Pregunta en lenguaje natural ("¿Mercadona está activa y quiénes son sus administradores?", "saca el CIF de estas 40 empresas", "¿esta empresa ha tenido un concurso?") y el asistente consulta la API con tu clave.
6
-
7
- ## Herramientas
8
-
9
- | Herramienta | Qué hace | Plan |
10
- |---|---|---|
11
- | `get_company` | Empresa por CIF: razón social, estado, constitución, provincia, CNAE, forma jurídica (ISO 20275) y LEI; domicilio, socio único, matriz del grupo y administradores según plan | Free (datos recortados), Pro |
12
- | `search_companies` | Buscar empresas por nombre | Free |
13
- | `verify_company` | Verificación KYB: existe, activa, nombre y administrador (o socio único) coinciden y, si se pide, NIF-IVA en VIES; con forma jurídica, LEI, matriz y socio único (2 consultas) | Pro |
14
- | `find_cif_by_name` | De nombre a CIF, hasta 100 a la vez, con provincia opcional para desempatar (solo cobra las coincidencias) | Pro |
15
- | `verify_invoice_recipients` | Valida una lista de clientes (hasta 100) antes de facturarles: razón social y domicilio oficiales, estado y `invoice_hint` ok / revisar / no_facturar, con sus motivos; con `vat`, también VIES (hasta 20). Solo cobra las sociedades encontradas (desde 1.4.0) | Pro |
16
- | `get_borme_history` | Actos publicados en el BORME | Pro |
17
- | `get_risk_profile` | Perfil de riesgo a partir del BORME | Business |
18
- | `get_public_contracts` | Contratos públicos adjudicados | Business |
19
- | `get_subsidies` | Subvenciones y ayudas públicas de la BDNS desde 2022 (Kit Digital incluido): resumen por año, instrumento y convocatoria, y las concesiones (desde 1.3.0) | Business |
20
- | `search_tenders` | Licitaciones públicas abiertas: por palabras, CPV, provincia, tipo e importe, o parecidas a lo que ya ha ganado una empresa (`cif`) | Business |
21
- | `check_sanctions` | Listas de sanciones de la UE, la ONU y OFAC: una empresa y sus administradores (`cif`) o un nombre (`name`), con el grado de cada coincidencia | Business |
22
- | `get_usage` | Plan, consultas disponibles y saldo de créditos (gratis; no funciona en el Sandbox) | Todos |
23
-
24
- Todas son de solo lectura. Cada llamada gasta consultas de tu plan, igual que la API.
25
-
26
- ## Instalación
27
-
28
- 1. Crea una cuenta gratis (100 consultas, sin tarjeta) en [apiempresas.es](https://apiempresas.es/register?intent=api&plan=free&source=mcp) y copia tu API key del panel.
29
- 2. Añade el servidor a tu cliente (necesita Node.js 18 o superior).
30
-
31
- ### Claude Desktop
32
-
33
- En `claude_desktop_config.json`:
34
-
35
- ```json
36
- {
37
- "mcpServers": {
38
- "apiempresas": {
39
- "command": "npx",
40
- "args": ["-y", "apiempresas-mcp"],
41
- "env": { "APIEMPRESAS_API_KEY": "tu_api_key" }
42
- }
43
- }
44
- }
45
- ```
46
-
47
- ### Claude Code
48
-
49
- ```bash
50
- claude mcp add apiempresas --env APIEMPRESAS_API_KEY=tu_api_key -- npx -y apiempresas-mcp
51
- ```
52
-
53
- ### Cursor
54
-
55
- En `~/.cursor/mcp.json` (o `.cursor/mcp.json` en el proyecto), el mismo bloque `mcpServers` que en Claude Desktop.
56
-
57
- ### VS Code
58
-
59
- En `.vscode/mcp.json`:
60
-
61
- ```json
62
- {
63
- "servers": {
64
- "apiempresas": {
65
- "type": "stdio",
66
- "command": "npx",
67
- "args": ["-y", "apiempresas-mcp"],
68
- "env": { "APIEMPRESAS_API_KEY": "tu_api_key" }
69
- }
70
- }
71
- }
72
- ```
73
-
74
- ### Pruebas sin coste
75
-
76
- Con `APIEMPRESAS_BASE_URL=https://apiempresas.es/api/sandbox/v1` las llamadas no gastan consultas (solo admite los CIF de prueba A15075062 y B00000000).
77
-
78
- ## Qué conviene saber
79
-
80
- - El estado registral, el scoring y el perfil de riesgo los calcula APIEmpresas a partir del BORME: no son un certificado del Registro Mercantil.
81
- - No cubre titular real, listas de sanciones o PEP, ni empresarios individuales (autónomos).
82
- - Precios: Free 100 consultas; Pro 19 €/mes (3.000/mes); Business 49 €/mes (10.000/mes); bonos sin suscripción desde 9 €. IVA no incluido. Detalle en [apiempresas.es](https://apiempresas.es/#precios).
83
- - Documentación completa de la API: [apiempresas.es/documentation](https://apiempresas.es/documentation).
84
-
85
- ## English
86
-
87
- Official MCP server for [APIEmpresas.es](https://apiempresas.es), a REST API for Spanish company data: lookup by CIF (tax ID), name search, KYB verification, bulk tax ID checks of invoice recipients (`verify_invoice_recipients`), directors, BORME (Commercial Registry gazette) filings, public contracts and risk profile. Get a free API key (100 requests) at apiempresas.es and run `npx -y apiempresas-mcp` with `APIEMPRESAS_API_KEY` set.
88
-
89
- ## Licencia
90
-
91
- MIT
1
+ # Spanish company data MCP server (SpainCompanyAPI)
2
+
3
+ Official [MCP](https://modelcontextprotocol.io) server for [SpainCompanyAPI](https://spaincompanyapi.com) (APIEmpresas.es): Spanish company data for Claude, Cursor, VS Code and any MCP-compatible assistant. Look up companies by tax ID (CIF/NIF), verify them (KYB), check a list of invoice recipients, and get directors, registry filings (BORME), sanctions screening, public contracts, grants and open tenders.
4
+
5
+ Ask in plain language ("Is Mercadona active and who are its directors?", "Find the tax IDs of these 40 companies", "Check these Spanish customers before I invoice them") and the assistant calls the API with your key.
6
+
7
+ - **Free API key:** 100 requests, no card required. [Sign up](https://spaincompanyapi.com/register?intent=api&plan=free&source=mcp)
8
+ - **API documentation:** [spaincompanyapi.com/docs](https://spaincompanyapi.com/docs)
9
+ - **Coverage:** over 4.7 million Spanish companies, updated every working day from the Commercial Registry gazette (BORME) and other public registers.
10
+
11
+ > Versión en español al final de este documento.
12
+
13
+ ## Tools
14
+
15
+ | Tool | What it does | Plan |
16
+ |---|---|---|
17
+ | `get_company` | Company by tax ID: legal name, status, incorporation date, province, CNAE activity, legal form (ISO 20275) and LEI; whether the Tax Agency has revoked its tax ID (`tax_id_revocation`); registered office, sole shareholder, parent company and directors depending on plan | Free (reduced data), Pro |
18
+ | `search_companies` | Search companies by name | Free |
19
+ | `verify_company` | KYB check (`/companies/verify`): the company exists and is operating, the name and the director (or sole shareholder) match and, if asked, the EU VAT number is in VIES; with legal form, LEI, parent and sole shareholder; fails if the Tax Agency has revoked the tax ID (2 requests) | Pro |
20
+ | `find_cif_by_name` | Name to tax ID, up to 100 at a time, with an optional province to break ties (only matches are charged) | Pro |
21
+ | `verify_invoice_recipients` | Checks a list of customers (up to 100) before invoicing them (`/companies/verify/batch`): legal name and registered office, status and `invoice_hint` ok / revisar (review) / no_facturar (do not invoice), with the reasons; with `vat`, also VIES (up to 20). Only companies found are charged | Pro |
22
+ | `get_borme_history` | Events published in the BORME | Pro |
23
+ | `get_risk_profile` | Risk profile based on the BORME | Business |
24
+ | `get_public_contracts` | Public contracts awarded | Business |
25
+ | `get_subsidies` | Public grants from the national grants database (BDNS) since 2022: summary by year, instrument and call, and the individual awards | Business |
26
+ | `search_tenders` | Open public tenders: by keywords, CPV, province, type and amount, or similar to what a company has already won (`cif`) | Business |
27
+ | `check_sanctions` | EU, UN and OFAC sanctions lists: a company and its directors (`cif`) or a name (`name`), with the strength of each match | Business |
28
+ | `get_usage` | Plan, requests left and credit balance (free; not available in the sandbox) | All |
29
+
30
+ All tools are read-only. Each call uses requests from your plan, as with the API.
31
+
32
+ ## Installation
33
+
34
+ 1. Create a free account (100 requests, no card) at [spaincompanyapi.com](https://spaincompanyapi.com/register?intent=api&plan=free&source=mcp) and copy your API key from the dashboard.
35
+ 2. Add the server to your client (requires Node.js 18 or later).
36
+
37
+ ### Claude Desktop
38
+
39
+ In `claude_desktop_config.json`:
40
+
41
+ ```json
42
+ {
43
+ "mcpServers": {
44
+ "apiempresas": {
45
+ "command": "npx",
46
+ "args": ["-y", "apiempresas-mcp"],
47
+ "env": { "APIEMPRESAS_API_KEY": "your_api_key" }
48
+ }
49
+ }
50
+ }
51
+ ```
52
+
53
+ ### Claude Code
54
+
55
+ ```bash
56
+ claude mcp add apiempresas --env APIEMPRESAS_API_KEY=your_api_key -- npx -y apiempresas-mcp
57
+ ```
58
+
59
+ ### Cursor
60
+
61
+ In `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project), the same `mcpServers` block as for Claude Desktop.
62
+
63
+ ### VS Code
64
+
65
+ In `.vscode/mcp.json`:
66
+
67
+ ```json
68
+ {
69
+ "servers": {
70
+ "apiempresas": {
71
+ "type": "stdio",
72
+ "command": "npx",
73
+ "args": ["-y", "apiempresas-mcp"],
74
+ "env": { "APIEMPRESAS_API_KEY": "your_api_key" }
75
+ }
76
+ }
77
+ }
78
+ ```
79
+
80
+ ### Remote server (nothing to install)
81
+
82
+ Clients that support remote MCP servers can connect to `https://spaincompanyapi.com/api/mcp` (also `https://apiempresas.es/api/mcp`) with the `X-API-KEY` header. Without a key, name search and basic company data still work, with a daily limit.
83
+
84
+ ### Testing at no cost
85
+
86
+ With `APIEMPRESAS_BASE_URL=https://spaincompanyapi.com/api/sandbox/v1` calls do not use requests (only the test tax IDs A15075062 and B00000000 work). With `APIEMPRESAS_BASE_URL=https://spaincompanyapi.com/api/v1` you use the live API with error messages in English; the default is `https://apiempresas.es/api/v1`.
87
+
88
+ ## Good to know
89
+
90
+ - Registry status, scoring and risk profile are worked out by SpainCompanyAPI from the BORME: they are not a certificate from the Commercial Registry.
91
+ - Not covered: ultimate beneficial owners, PEP screening, credit scores, full annual accounts and sole traders (autónomos).
92
+ - Pricing: Free 100 requests; Pro €19/month (3,000/month); Business €49/month (10,000/month); credit packs without subscription. VAT not included. Details at [spaincompanyapi.com](https://spaincompanyapi.com/spanish-company-data-api).
93
+
94
+ ## Links
95
+
96
+ - Website: [spaincompanyapi.com](https://spaincompanyapi.com)
97
+ - API documentation: [spaincompanyapi.com/docs](https://spaincompanyapi.com/docs)
98
+ - MCP setup guide: [spaincompanyapi.com/docs#mcp](https://spaincompanyapi.com/docs#mcp)
99
+ - Support: soporte@apiempresas.es
100
+
101
+ ## License
102
+
103
+ MIT
104
+
105
+ ---
106
+
107
+ ## En español
108
+
109
+ Servidor MCP oficial de [APIEmpresas.es](https://apiempresas.es): datos de empresas españolas para Claude, Cursor, VS Code y cualquier asistente compatible con MCP. Las herramientas son las de la tabla de arriba: empresa por CIF, búsqueda por nombre, verificación KYB, de nombre a CIF, validación del NIF de los clientes antes de facturar (`verify_invoice_recipients`), BORME, riesgo, contratos públicos, subvenciones, licitaciones abiertas y listas de sanciones.
110
+
111
+ ```bash
112
+ claude mcp add apiempresas --env APIEMPRESAS_API_KEY=tu_api_key -- npx -y apiempresas-mcp
113
+ ```
114
+
115
+ Crea una cuenta gratis (100 consultas, sin tarjeta) en [apiempresas.es](https://apiempresas.es/register?intent=api&plan=free&source=mcp). Para probar sin gastar consultas: `APIEMPRESAS_BASE_URL=https://apiempresas.es/api/sandbox/v1`. Documentación completa en [apiempresas.es/documentation](https://apiempresas.es/documentation).
package/dist/index.js CHANGED
@@ -14,7 +14,7 @@
14
14
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
15
15
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
16
16
  import { z } from 'zod';
17
- export const VERSION = '1.4.0';
17
+ export const VERSION = '1.4.2';
18
18
  const API_KEY = (process.env.APIEMPRESAS_API_KEY || '').trim();
19
19
  const BASE_URL = (process.env.APIEMPRESAS_BASE_URL || 'https://apiempresas.es/api/v1').replace(/\/+$/, '');
20
20
  const TIMEOUT_MS = 30_000;
@@ -142,7 +142,7 @@ export function crearServidor() {
142
142
  const server = new McpServer({ name: 'apiempresas', version: VERSION });
143
143
  server.registerTool('get_company', {
144
144
  title: 'Empresa por CIF',
145
- description: "Ficha de UNA empresa española cuando ya tienes su CIF/NIF. Úsala para saber si existe y está activa, su razón social, forma jurídica (con código ISO 20275), código LEI, CNAE, provincia y fecha de constitución; con plan Pro, también domicilio, tramo de facturación, socio único, matriz del grupo y, con include_directors, los administradores vigentes. Si no tienes el CIF, usa search_companies; para decidir un alta (KYB), verify_company. Gasta 1 consulta. Spanish company lookup by tax ID.",
145
+ description: "Ficha de UNA empresa española cuando ya tienes su CIF/NIF. Úsala para saber si existe y está activa, su razón social, forma jurídica (con código ISO 20275), código LEI, CNAE, provincia y fecha de constitución; con plan Pro, también domicilio, tramo de facturación, socio único, matriz del grupo y, con include_directors, los administradores vigentes. En todos los planes avisa si la Agencia Tributaria ha revocado (o rehabilitado) su NIF según el BOE (tax_id_revocation): con el NIF revocado no vale ante Hacienda y los bancos no pueden hacerle cobros ni pagos. Si no tienes el CIF, usa search_companies; para decidir un alta (KYB), verify_company. Gasta 1 consulta. Spanish company lookup by tax ID.",
146
146
  inputSchema: {
147
147
  cif: cifSchema,
148
148
  include_directors: z
@@ -163,7 +163,7 @@ export function crearServidor() {
163
163
  }, async ({ query, limit }) => llamar(`/companies/search?${qs({ q: query, multiple: true, limit: limit ?? 10 })}`));
164
164
  server.registerTool('verify_company', {
165
165
  title: 'Verificación KYB',
166
- description: "Verificación para dar de alta a un cliente o proveedor (KYB) en una llamada: comprueba que la sociedad existe y opera, que la razón social que te han dado coincide (name), que quien firma es administrador vigente o socio único (person) y, si se pide, el NIF-IVA en VIES (vat). Devuelve alertas y una recomendación pass / review / fail, además de forma jurídica, LEI, matriz y socio único. Úsala para decidir; para solo consultar datos, get_company. Plan Pro; gasta 2 consultas. KYB check for a Spanish company.",
166
+ description: "Verificación para dar de alta a un cliente o proveedor (KYB) en una llamada: comprueba que la sociedad existe y opera, que la razón social que te han dado coincide (name), que quien firma es administrador vigente o socio único (person) y, si se pide, el NIF-IVA en VIES (vat). Da fail si la Agencia Tributaria ha revocado su NIF (alerta TAX_ID_REVOKED). Devuelve alertas y una recomendación pass / review / fail, además de forma jurídica, LEI, matriz y socio único. Úsala para decidir; para solo consultar datos, get_company. Plan Pro; gasta 2 consultas. KYB check for a Spanish company.",
167
167
  inputSchema: {
168
168
  cif: cifSchema,
169
169
  name: z.string().optional().describe('Razón social que ha declarado el cliente, para comprobar que coincide'),
@@ -190,7 +190,7 @@ export function crearServidor() {
190
190
  // 1.4.0 (26-10-2026): igual que en el servidor remoto (app/Libraries/McpServer.php)
191
191
  server.registerTool('verify_invoice_recipients', {
192
192
  title: 'Validar NIF de clientes para facturar',
193
- description: "Valida una LISTA de clientes (hasta 100) antes de emitirles facturas (Verifactu, factura electrónica): por cada NIF, si el formato es válido, si la sociedad consta, su razón social y domicilio oficiales, su estado y, si das el nombre que tienes guardado, si coincide. Devuelve invoice_hint ok / revisar / no_facturar con los motivos (extinguida, absorbida, en concurso, nombre distinto, NIF de ejemplo...). Úsala para revisar la cartera de clientes de un programa de facturación o ERP; para dar de alta a un solo cliente con más detalle, verify_company. No sustituye al censo de la AEAT. Plan Pro, Business o saldo; gasta 1 consulta por sociedad encontrada (lo que no consta no se cobra). Bulk VAT/tax ID check of invoice recipients.",
193
+ description: "Valida una LISTA de clientes (hasta 100) antes de emitirles facturas (Verifactu, factura electrónica): por cada NIF, si el formato es válido, si la sociedad consta, su razón social y domicilio oficiales, su estado y, si das el nombre que tienes guardado, si coincide. Devuelve invoice_hint ok / revisar / no_facturar con los motivos (extinguida, absorbida, en concurso, NIF revocado por la AEAT, nombre distinto, NIF de ejemplo...). Úsala para revisar la cartera de clientes de un programa de facturación o ERP; para dar de alta a un solo cliente con más detalle, verify_company. No sustituye al censo de la AEAT. Plan Pro, Business o saldo; gasta 1 consulta por sociedad encontrada (lo que no consta no se cobra). Bulk VAT/tax ID check of invoice recipients.",
194
194
  inputSchema: {
195
195
  items: z
196
196
  .array(z.object({
package/package.json CHANGED
@@ -1,48 +1,70 @@
1
- {
2
- "name": "apiempresas-mcp",
3
- "version": "1.4.0",
4
- "description": "Servidor MCP oficial de APIEmpresas.es: datos de empresas españolas (CIF, BORME, administradores, KYB, listas de sanciones, licitaciones abiertas, riesgo) para Claude, Cursor y otros asistentes de IA",
5
- "mcpName": "io.github.abasmartinc/apiempresas",
6
- "type": "module",
7
- "bin": {
8
- "apiempresas-mcp": "dist/index.js"
9
- },
10
- "main": "dist/index.js",
11
- "files": [
12
- "dist",
13
- "README.md",
14
- "LICENSE"
15
- ],
16
- "engines": {
17
- "node": ">=18"
18
- },
19
- "scripts": {
20
- "build": "tsc",
21
- "test": "npm run build && node tests/smoke.mjs",
22
- "prepublishOnly": "npm run build"
23
- },
24
- "keywords": [
25
- "mcp",
26
- "model-context-protocol",
27
- "apiempresas",
28
- "empresas",
29
- "cif",
30
- "nif",
31
- "borme",
32
- "registro mercantil",
33
- "kyb",
34
- "spain",
35
- "spanish companies"
36
- ],
37
- "homepage": "https://apiempresas.es",
38
- "author": "APIEmpresas",
39
- "license": "MIT",
40
- "dependencies": {
41
- "@modelcontextprotocol/sdk": "^1.32.1",
42
- "zod": "^3.25.0"
43
- },
44
- "devDependencies": {
45
- "@types/node": "^20.11.19",
46
- "typescript": "^5.3.3"
47
- }
48
- }
1
+ {
2
+ "name": "apiempresas-mcp",
3
+ "version": "1.4.2",
4
+ "description": "Official MCP server for SpainCompanyAPI (APIEmpresas.es): Spanish company data for Claude, Cursor and other AI assistants. Tax ID (CIF/NIF) lookup, KYB verification, invoice recipient checks, directors, BORME filings, sanctions screening, public tenders and risk.",
5
+ "mcpName": "io.github.abasmartinc/apiempresas",
6
+ "type": "module",
7
+ "bin": {
8
+ "apiempresas-mcp": "dist/index.js"
9
+ },
10
+ "main": "dist/index.js",
11
+ "files": [
12
+ "dist",
13
+ "README.md",
14
+ "LICENSE"
15
+ ],
16
+ "engines": {
17
+ "node": ">=18"
18
+ },
19
+ "scripts": {
20
+ "build": "tsc",
21
+ "test": "npm run build && node tests/smoke.mjs",
22
+ "prepublishOnly": "npm run build"
23
+ },
24
+ "keywords": [
25
+ "mcp",
26
+ "mcp-server",
27
+ "model-context-protocol",
28
+ "claude",
29
+ "cursor",
30
+ "ai-agents",
31
+ "spain",
32
+ "spanish companies",
33
+ "company data",
34
+ "kyb",
35
+ "know your business",
36
+ "company verification",
37
+ "tax id validation",
38
+ "cif",
39
+ "nif",
40
+ "vies",
41
+ "e-invoicing",
42
+ "borme",
43
+ "commercial registry",
44
+ "sanctions screening",
45
+ "public tenders",
46
+ "apiempresas",
47
+ "spaincompanyapi",
48
+ "empresas",
49
+ "registro mercantil"
50
+ ],
51
+ "homepage": "https://spaincompanyapi.com",
52
+ "repository": {
53
+ "type": "git",
54
+ "url": "git+https://github.com/abasmartinc/apiempresas-mcp.git"
55
+ },
56
+ "bugs": {
57
+ "url": "https://github.com/abasmartinc/apiempresas-mcp/issues",
58
+ "email": "soporte@apiempresas.es"
59
+ },
60
+ "author": "APIEmpresas",
61
+ "license": "MIT",
62
+ "dependencies": {
63
+ "@modelcontextprotocol/sdk": "^1.32.1",
64
+ "zod": "^3.25.0"
65
+ },
66
+ "devDependencies": {
67
+ "@types/node": "^20.11.19",
68
+ "typescript": "^5.3.3"
69
+ }
70
+ }