ayudas-es-mcp

Servidor MCP que da a una IA acceso a dos fuentes oficiales españolas, sin scraping ni claves:

• BDNS / infosubvenciones.es: convocatorias de ayudas y subvenciones de todas las administraciones (Estado, comunidades, diputaciones y ayuntamientos).
• BOE (API de datos abiertos): normativa, oposiciones, licitaciones.

Se consultan en directo: no hay base de datos que descargar ni sincronizar, así que funciona al instalarlo y los datos están siempre al día. Lo que añade a la API: recuentos exactos, plazos calculados, separación de las ayudas que de verdad se pueden pedir, lectura de las bases en PDF y un calendario previsto de las convocatorias que se repiten cada año. Y avisa de lo que no sabe en lugar de callarlo.

Instalación

Requiere Node.js 22.13 o superior. No hay que instalar ni configurar nada más.

Claude Code

claude mcp add ayudas -- npx -y ayudas-es-mcp

Claude Desktop, Cursor y otros clientes

{
  "mcpServers": {
    "ayudas": {
      "command": "npx",
      "args": ["-y", "ayudas-es-mcp"]
    }
  }
}

Herramientas

Herramienta	Qué hace
ayudas_buscar	Ayudas por texto, comunidad, beneficiario (autónomo/pyme, particular…), finalidad, instrumento y administración. Total exacto + muestra con estado, plazo y presupuesto.
ayudas_recuento	Recuentos y rankings exactos por comunidad, finalidad, beneficiario, instrumento, administración, órgano, mes o año.
ayudas_previstas	Calendario previsto: ayudas que se convocan cada año y que, por su histórico desde 2021, saldrán en los próximos días, o que este año se están retrasando. Con su fiabilidad medida.
ayuda_detalle	Ficha completa: plazo interpretado, extracto oficial (requisitos, cuantía, cómo pedirla), bases, documentos e historial si se convoca cada año.
ayuda_texto	Lee el PDF de las bases: devuelve el texto literal de sus apartados (cuantía, plazo, beneficiarios, requisitos, documentación, criterios…) con el número de página; o las páginas o palabras que se pidan.
novedades_perfil	Boletín para un perfil: ayudas nuevas sin cerrar + BOE sobre sus temas.
estado_datos	De dónde salen los datos, estado de la caché y del calendario.
boe_sumario_dia	Publicaciones del BOE de un día, filtrables por palabras y sección.
boe_buscar	Búsqueda en el BOE en un rango de fechas por palabras y/o sección (2B oposiciones, 5A licitaciones).
boe_documento	Texto de una disposición del BOE.

Todas están marcadas como de solo lectura (anotaciones MCP), así que los clientes que lo admiten no piden confirmación en cada llamada. El servidor envía además unas instrucciones al modelo: qué herramienta usar para contar o para leer requisitos, y que cite el código y los avisos en lugar de completar con datos inventados.

Prompts

Prompt	Qué hace
ayudas_para_mi	A partir de un perfil («autónoma, peluquería en Bilbao»): ayudas abiertas, las que suelen salir pronto y la cuantía y requisitos de las mejores, en una tabla.
analizar_convocatoria	Ficha de una convocatoria por su código: plazo, cuantía, requisitos y documentación, citando página.

En Claude Desktop y Claude Code aparecen como comandos (/).

Ejemplos de preguntas

• «¿Qué ayudas abiertas hay para autónomos en Galicia para digitalización?»
• «¿Qué ayudas para pymes del País Vasco suelen salir en los próximos dos meses?»
• «¿Hay alguna ayuda que salga todos los años por estas fechas y este año aún no haya salido?»
• «¿Qué comunidad ha convocado más ayudas de vivienda este año?»
• «¿Cuántas ayudas para pymes se han convocado cada mes desde mayo?»
• «Hazme el resumen semanal para una pyme de hostelería en Andalucía.»
• «¿Ha salido alguna oposición de enfermería en el BOE este mes?»

Cómo funciona

Cada pregunta se traduce a consultas a la API oficial de la BDNS:

• Totales exactos con una sola petición. La API devuelve el número de coincidencias de una búsqueda sin descargarla; un recuento simple cuesta una petición, y un ranking, una por grupo.
• Búsqueda por palabras en dos pasos. La API busca subcadenas («tala» encuentra «instalación»). Se le envía la raíz de cada palabra y sobre lo que devuelve se aplican las reglas de palabra (ver abajo). Comprobado: da exactamente lo mismo que descargar todo el listado y filtrarlo (8 de 8 casos, incluidos prefijos, siglas y títulos en euskera).
• Detalle solo de lo que se muestra: plazo, presupuesto y tipo están en la ficha de cada convocatoria, que se pide al enseñarla.
• Ritmo prudente: como mucho una petición por segundo a la BDNS, que bloquea las ráfagas.

Caché temporal

Las respuestas se guardan en ~/.cache/ayudas-es-mcp/cache.sqlite (o solo en memoria si no se puede escribir), con una caducidad según lo que puede cambiar:

Dato	Se guarda
Totales y listados de un periodo que acabó hace más de 7 días	1 semana
Totales y listados que incluyen días recientes	1 hora
Ficha con plazo provisional (pendiente de publicar el extracto)	1 día
Ficha de una convocatoria cerrada o sin solicitud	1 mes
Otras fichas	1 semana
Texto extraído de un PDF	1 mes
Calendario previsto (solo las series calculadas, no el histórico)	1 semana

No es una copia de la BDNS: solo guarda lo ya preguntado. Dos preguntas iguales a la vez comparten la petición. npx ayudas-es-mcp --vaciar-cache la borra.

Tiempos

Medidos con la caché vacía, a una petición por segundo:

Consulta	Primera vez	Repetida
Buscar «digital*» para pymes, 3 abiertas	~4 s	inmediata
Buscar en Galicia, 10 abiertas	~12 s	~1 s
Recuento por mes, pymes desde mayo	~7 s	inmediata
Recuento por órgano de «euskera» en el País Vasco (todo el histórico)	~2 s	inmediata
Ranking por comunidad, vivienda en 2026	~21 s	inmediata
Calendario previsto	2-3 min, una vez por semana y en segundo plano	inmediata

El calendario necesita el histórico desde 2021 (~40 peticiones): se prepara en segundo plano la primera vez que se usa una herramienta de ayudas, no al arrancar, y entretanto ayudas_previstas dice que se está preparando en lugar de responder «no hay».

Cómo se evita dar información errónea

Una herramienta que se equivoca con seguridad es peor que ninguna. Por eso:

Riesgo	Qué se hace
Decir «no hay ayudas» cuando solo la búsqueda no encontró	La respuesta vacía lo advierte: la búsqueda es por palabras del título y no prueba que no existan
Contar sobre una muestra	ayudas_buscar da el total exacto y marca la lista como muestra; para contar hay ayudas_recuento
Ayudas que ya no se pueden pedir	Distingue cerradas, sin solicitud (concesión directa) y abiertas; las instrumentales (72 % de lo reciente) se separan
Sumar presupuestos parciales	La BDNS no da el presupuesto en bloque, así que los recuentos no lo suman; el de cada convocatoria está en su ficha
Mirar solo los últimos 90 días sin decirlo	Lo indica y cuenta cuántas más hay registradas antes con los mismos filtros
Descargar miles de filas para una pregunta	Si excluir concesiones directas exige descargar más de 30.000 filas, pide acotar en vez de hacerlo
«Hoy» equivocado de madrugada	Las fechas (plazos, BOE de hoy) van en hora peninsular española, no en UTC
Una fuente lenta o caída	Cada petición tiene tiempo máximo y reintentos; un fallo puntual no tumba la respuesta entera, se avisa de lo que falta
Calendario aún sin preparar	Dice que se está preparando, en vez de «0 ayudas recurrentes»
Calendario sobre ayudas que no son una sola	Marca las series en las que el órgano registra varias al año con el mismo título
Citar de un PDF algo que no está	Devuelve texto literal con página, distingue apartado de mención y avisa si no localiza un tema en lugar de inventarlo
Texto de un PDF con instrucciones	Se entrega marcado como dato literal de un documento externo
Código que no existe	Error inmediato y claro, no un reintento de 30 s

Lectura de las bases (PDF)

ayuda_texto descarga el PDF de la convocatoria y devuelve texto literal con página, sin resumir ni usar IA. Solo se hace bajo demanda y el texto se guarda en la caché: cada documento se descarga y procesa una sola vez.

• Elige el documento por su nombre: prefiere «texto íntegro» o «bases» a un anexo, formulario o acuerdo de aprobación; si el elegido no deja localizar apartados, prueba con los siguientes más probables. Si el elegido no se puede leer (un Word, demasiado grande), pasa al siguiente y lo dice. La respuesta lista los demás para poder pedirlos (documento).
• Localiza apartados por su título (Artículo, Base, «Primero.-», «6. Plazo…», MAYÚSCULAS), descartando frases partidas por el ancho de página, la protección de datos y los anexos con formularios. Distingue apartado (hay un título que corresponde) de mención (solo se nombra el tema), y lo dice.
• Con buscar y paginas se puede ir directamente a una palabra o a unas páginas cuando los apartados no se reconocen.
• Cantidades en euros del documento, cada una con la frase en la que aparece.
• El contenido del PDF se entrega como dato, no como instrucciones: se marca como texto literal de un documento externo.

Probado con 15 convocatorias reales (ayuntamientos, diputaciones, universidades): localiza la cuantía en 15, el plazo en 14, los beneficiarios en 14 y los requisitos en 14.

Límites: PDF escaneados sin capa de texto (se avisa; no hay OCR), documentos Word u otros formatos, y archivos de más de 25 MB o 200 páginas (se leen las primeras). Los apartados se detectan con reglas: comprueba siempre la página citada.

Plazo real de cada convocatoria

La BDNS solo trae fechas de solicitud en una parte de las convocatorias. En el resto el plazo viene en texto, y se interpreta de forma determinista (sin LLM):

El texto dice	Resultado
Tipo «Concesión directa - instrumental»	⚫ no se puede solicitar: es el registro de una ayuda ya concedida a un beneficiario concreto (sus fechas son de ejecución)
«Hasta el 30 de noviembre de 2026», «31 de decembro», «1/3/27»	🟢/🔴 según la fecha (castellano, gallego y catalán)
«10 días hábiles desde el día siguiente a la publicación» y el extracto ya está publicado	🟢 fecha de fin calculada con el calendario
Lo mismo, pero el extracto aún no se ha publicado	🟡 pendiente de publicar
«Sin plazo de solicitud», «no procede», «nominativa»…	⚫ no se puede solicitar
Varios plazos, inicio no estándar («a partir del quinto día hábil»…)	⚪ consultar (no se arriesga una fecha)

Medido sobre 1.004 convocatorias recientes con detalle: el 72 % son instrumentales (antes aparecían como «abiertas» por tener fechas), y solo el 2 % queda como «consultar».

El cálculo sigue la Ley 39/2015, art. 30: días hábiles sin sábados, domingos ni festivos; meses hasta el mismo día del mes de vencimiento; si el último día es inhábil, el siguiente hábil. Los festivos nacionales y autonómicos vienen de Nager.Date (los de la comunidad cuando todas las regiones de la convocatoria son de una sola); los locales no se incluyen, por eso la respuesta dice siempre que es un cálculo y cómo se ha hecho. Pruebas con casos comprobados a mano en src/plazos.test.ts.

Calendario previsto (ayudas recurrentes)

Se agrupan las convocatorias del mismo órgano con el mismo título sin años, fechas ni ediciones («XIV Premios X 2026» ≈ «XV Premios X 2027»). Las convocadas en 3 o más años forman una serie con su fecha típica de registro (mediana circular, para que 28-dic y 3-ene estén cerca) y su variación. Se excluyen las nominativas, directas y convenios, que no se pueden solicitar.

Fiabilidad medida (prever 2025 usando solo 2021-2024 y compararlo con lo ocurrido):

Confianza	Error mediano	A ±15 días
Alta (4+ años, variación ≤ 15 días)	15 días	51 %
Media	26 días	35 %
Baja (oculta por defecto)	55 días	15 %

Además, solo el 59 % de las series activas en 2024 volvió a convocarse en 2025 con el mismo título (otras cambian de nombre o dejan de convocarse). La evaluación se recalcula con cada calendario y la herramienta la muestra, para que la IA pueda decir cuánto fiarse.

Búsqueda por palabras

Sobre el título (y el título cooficial en euskera, catalán o gallego), sin tildes, con límite de palabra («tala» no coincide con «instalación»), singular/plural («pyme» ↔ «pymes») y prefijo con * («digital*» → digitalización, digitales). No es semántica: «digitalización» no encuentra «transformación tecnológica»; para temas amplios conviene usar finalidad.

Opciones

npx ayudas-es-mcp --help
npx ayudas-es-mcp --vaciar-cache
npx ayudas-es-mcp --version

Variables: AYUDAS_CACHE (ruta de la caché), BDNS_INTERVALO_MS (ritmo de peticiones, 1000 por defecto) y AYUDAS_TIMEOUT_MS (tiempo máximo por petición, 30000 por defecto).

Desarrollo

git clone … && cd ayudas-es-mcp
npm install
npm run build
npm test            # pruebas sin red: plazos, lectura de documentos, fechas, caché
npm run test:live   # búsqueda en directo frente a la referencia + prueba de extremo a extremo

Limitaciones conocidas

• Estado de las ayudas. La BDNS no indica si una convocatoria está abierta (su campo abierto viene siempre a false y sus filtros de abierta/tipo se ignoran en silencio): se deduce del plazo interpretado. Los plazos calculados no incluyen festivos locales.
• Concesiones directas. Solo se sabe con seguridad cuáles son con el detalle de cada convocatoria. En búsquedas y recuentos, el filtro excluir_directas las estima por el título: precisión ~97 %, detecta ~67 %. Los recuentos sin ese filtro las incluyen y lo advierten. Excluirlas en periodos muy largos sin otros filtros exigiría descargar decenas de miles de filas, así que se pide acotar.
• Presupuestos y ayudas antiguas. El presupuesto y el plazo solo constan en la ficha de cada convocatoria, así que los recuentos no suman presupuestos y la búsqueda no localiza ayudas registradas hace meses que sigan abiertas (avisa de cuántas hay antes del periodo).
• Rankings la primera vez. Agrupar por comunidad o finalidad cuesta una petición por grupo (~20 s); repetido, sale de la caché.
• El calendario predice el registro en la BDNS, no el plazo de solicitud, y no detecta una ayuda que cambie de nombre. Acierta a ±15 días en el 35-51 % de los casos (ver arriba).
• Comunidad. ~2 % de las convocatorias no tienen comunidad autónoma asignada en la BDNS.
• Mismo título, distintas ayudas. Hay órganos que registran decenas de ayudas individuales bajo un mismo título; no son duplicados, así que no se eliminan. Cuando se descargan las filas, los recuentos dan también los «títulos distintos».
• Lectura de PDF. Sin OCR (los escaneados no se leen) y por reglas, no por IA: ver arriba.
• Varias instancias. El límite de una petición por segundo es por proceso: varios clientes abiertos a la vez suman su ritmo (comparten, eso sí, la caché en disco).

Datos y licencia

• BDNS. Origen de los datos: Intervención General de la Administración del Estado. Se reutilizan según su aviso legal, que permite el uso comercial y no comercial citando la fuente y sin desnaturalizar la información. Este servidor solo consulta convocatorias, no datos personales de beneficiarios.
• BOE. API de datos abiertos de la Agencia Estatal Boletín Oficial del Estado.
• Festivos. Nager.Date.

Proyecto independiente: no está afiliado a la IGAE, a la Agencia Estatal BOE ni a ningún organismo público, ni cuenta con su respaldo. La información puede cambiar o corregirse en la fuente: compruébala siempre en la ficha oficial antes de presentar una solicitud.