apiempresas-mcp 1.4.1 → 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 +64 -40
  2. package/dist/index.js +1 -1
  3. package/package.json +70 -48
package/README.md CHANGED
@@ -1,36 +1,42 @@
1
- # APIEmpresas MCP
1
+ # Spanish company data MCP server (SpainCompanyAPI)
2
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.
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
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.
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
6
 
7
- ## Herramientas
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.
8
10
 
9
- | Herramienta | Qué hace | Plan |
11
+ > Versión en español al final de este documento.
12
+
13
+ ## Tools
14
+
15
+ | Tool | What it does | Plan |
10
16
  |---|---|---|
11
- | `get_company` | Empresa por CIF: razón social, estado, constitución, provincia, CNAE, forma jurídica (ISO 20275) y LEI; si la AEAT ha revocado su NIF (`tax_id_revocation`, desde 1.4.1); 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; fail si la AEAT ha revocado el NIF (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).
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).
30
36
 
31
37
  ### Claude Desktop
32
38
 
33
- En `claude_desktop_config.json`:
39
+ In `claude_desktop_config.json`:
34
40
 
35
41
  ```json
36
42
  {
@@ -38,7 +44,7 @@ En `claude_desktop_config.json`:
38
44
  "apiempresas": {
39
45
  "command": "npx",
40
46
  "args": ["-y", "apiempresas-mcp"],
41
- "env": { "APIEMPRESAS_API_KEY": "tu_api_key" }
47
+ "env": { "APIEMPRESAS_API_KEY": "your_api_key" }
42
48
  }
43
49
  }
44
50
  }
@@ -47,16 +53,16 @@ En `claude_desktop_config.json`:
47
53
  ### Claude Code
48
54
 
49
55
  ```bash
50
- claude mcp add apiempresas --env APIEMPRESAS_API_KEY=tu_api_key -- npx -y apiempresas-mcp
56
+ claude mcp add apiempresas --env APIEMPRESAS_API_KEY=your_api_key -- npx -y apiempresas-mcp
51
57
  ```
52
58
 
53
59
  ### Cursor
54
60
 
55
- En `~/.cursor/mcp.json` (o `.cursor/mcp.json` en el proyecto), el mismo bloque `mcpServers` que en Claude Desktop.
61
+ In `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project), the same `mcpServers` block as for Claude Desktop.
56
62
 
57
63
  ### VS Code
58
64
 
59
- En `.vscode/mcp.json`:
65
+ In `.vscode/mcp.json`:
60
66
 
61
67
  ```json
62
68
  {
@@ -65,27 +71,45 @@ En `.vscode/mcp.json`:
65
71
  "type": "stdio",
66
72
  "command": "npx",
67
73
  "args": ["-y", "apiempresas-mcp"],
68
- "env": { "APIEMPRESAS_API_KEY": "tu_api_key" }
74
+ "env": { "APIEMPRESAS_API_KEY": "your_api_key" }
69
75
  }
70
76
  }
71
77
  }
72
78
  ```
73
79
 
74
- ### Pruebas sin coste
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.
75
83
 
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).
84
+ ### Testing at no cost
77
85
 
78
- ## Qué conviene saber
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`.
79
87
 
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).
88
+ ## Good to know
84
89
 
85
- ## English
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).
86
93
 
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 [spaincompanyapi.com](https://spaincompanyapi.com/register?intent=api&plan=free&source=mcp_readme) (English documentation: [spaincompanyapi.com/docs](https://spaincompanyapi.com/docs)) and run `npx -y apiempresas-mcp` with `APIEMPRESAS_API_KEY` set.
94
+ ## Links
88
95
 
89
- ## Licencia
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
90
102
 
91
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.1';
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;
package/package.json CHANGED
@@ -1,48 +1,70 @@
1
- {
2
- "name": "apiempresas-mcp",
3
- "version": "1.4.1",
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
+ }