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.
- package/README.md +115 -91
- package/dist/index.js +4 -4
- package/package.json +70 -48
package/README.md
CHANGED
|
@@ -1,91 +1,115 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
|
16
|
-
|
|
17
|
-
| `
|
|
18
|
-
| `
|
|
19
|
-
| `
|
|
20
|
-
| `
|
|
21
|
-
| `
|
|
22
|
-
| `
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
###
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
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.
|
|
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.
|
|
4
|
-
"description": "
|
|
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
|
-
"
|
|
27
|
-
"
|
|
28
|
-
"
|
|
29
|
-
"
|
|
30
|
-
"
|
|
31
|
-
"
|
|
32
|
-
"
|
|
33
|
-
"
|
|
34
|
-
"
|
|
35
|
-
"
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
"
|
|
42
|
-
"
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
"
|
|
46
|
-
"
|
|
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
|
+
}
|