io.github.plopez053/ayudas-es

ayudas-es-mcp

Guía de uso del servidor MCP de ayudas y subvenciones de España.

Permite que una IA consulte dos fuentes oficiales, sin claves ni scraping:

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

Las consultas se hacen en directo. No hay que descargar ni sincronizar ninguna base de datos: se instala y funciona.

Qué aporta

Sobre la API de la BDNS, el servidor añade:

• Recuentos exactos, no estimados sobre una muestra.
• Plazos de solicitud calculados a partir del texto de cada convocatoria.
• Separación de las ayudas que realmente se pueden pedir.
• Lectura de las bases en PDF, con el número de página de cada cita.
• Un calendario previsto de las convocatorias que se repiten cada año.
• Avisos explícitos cuando no sabe algo, en lugar de callarlo.

1. Requisitos

• Node.js 22.13 o superior.
• Un cliente compatible con MCP (Claude Code, Claude Desktop, Cursor u otro).

No hace falta instalar nada más ni configurar claves.

2. Instalación

Claude Code

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

Claude Desktop, Cursor y otros clientes

Añade este bloque a la configuración MCP del cliente y reinícialo:

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

3. Comprobar que funciona

En una terminal:

npx ayudas-es-mcp --version

En el cliente, pregunta por ejemplo: «¿Qué ayudas abiertas hay para autónomos en Galicia para digitalización?». Si el servidor está activo, la IA usará las herramientas ayudas_*.

4. Qué se le puede preguntar

• «¿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?»

Hay además dos prompts, que los clientes muestran como comandos (/):

5. Herramientas

Todas son de solo lectura (anotación MCP), por lo que los clientes que lo admiten no piden confirmación en cada llamada. Los valores de las listas cerradas (comunidad, beneficiario, finalidad…) admiten mayúsculas, tildes y nombres habituales: «País Vasco», «Euskadi» o «pymes» valen igual que pais-vasco o autonomo-o-pyme.

El servidor envía además instrucciones al modelo: qué herramienta usar para contar o para leer requisitos, y que cite códigos y avisos en lugar de completar con datos inventados.

6. Configuración

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

Variables de entorno opcionales:

Caché

Las respuestas se guardan en disco (o solo en memoria si no se puede escribir) para no repetir peticiones. No es una copia de la BDNS: solo guarda lo ya consultado. La duración depende de cuánto puede cambiar cada dato:

El histórico del calendario ocupa unos 25 MB en disco (unos 4 MB por año).

7. Cómo funciona

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

• Totales exactos con una sola petición. La API devuelve cuántas coincidencias tiene 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» encontraría «instalación»). Se le envía la raíz de cada palabra y sobre su respuesta se aplican las reglas de palabra descritas más abajo.
• Detalle solo de lo que se muestra. Plazo, presupuesto y tipo están en la ficha de cada convocatoria, que se pide únicamente al enseñarla.
• Ritmo prudente. Como máximo una petición por segundo a la BDNS, que bloquea las ráfagas.

Búsqueda por palabras

Se busca en el título (y en el título cooficial en euskera, catalán o gallego), sin tildes, con límite de palabra, singular y plural equivalentes («pyme» y «pymes») y prefijo con * («digital*» encuentra digitalización y digitales). Para temas amplios conviene usar finalidad.

Los términos habituales se amplían con sus sinónimos: «autónomos» encuentra también «por cuenta propia» y «autoempleo»; «pymes», «pequeñas y medianas empresas» y «microempresa»; «vehículo eléctrico», «movilidad eléctrica» y «MOVES». La lista está en src/texto.ts y solo recoge equivalencias estrechas, revisadas sobre títulos reales. Deja fuera las palabras que suelen formar parte del nombre de un organismo, como «empleo» en «Consejería de Empleo», porque añaden sobre todo ruido. Las palabras de un sinónimo deben aparecer en orden y juntas, con como mucho dos palabras en medio. La respuesta indica qué términos se han añadido, y con sinonimos: false se busca solo lo escrito. Una palabra con * no se amplía. Fuera de la lista no hay búsqueda semántica: «digitalización» no encuentra «transformación tecnológica».

Los sinónimos no cuestan peticiones de más: la API admite buscar «cualquiera de estas palabras», y el filtro exacto se aplica después.

Plazo 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 con reglas, sin IA:

El cálculo sigue la Ley 39/2015, art. 30: días hábiles sin sábados, domingos ni festivos; los meses acaban el mismo día del mes de vencimiento; si el último día es inhábil, pasa al siguiente hábil. Los festivos nacionales y autonómicos vienen de Nager.Date. Los locales no se incluyen, y por eso la respuesta indica siempre que es un cálculo y cómo se hizo. Los casos comprobados a mano están en src/plazos.test.ts.

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 cada documento se procesa una vez.

• Elige el documento por su nombre: prefiere «texto íntegro» o «bases» a un anexo, un formulario o un acuerdo de aprobación. Si el elegido no se puede leer, 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). Distingue apartado (hay un título que corresponde) de mención (solo se nombra el tema).
• Con buscar y paginas se puede ir directamente a una palabra o a unas páginas cuando los apartados no se reconocen.
• Extrae las cantidades en euros, cada una con la frase en la que aparece.
• El contenido del PDF se entrega marcado como texto literal de un documento externo, no como instrucciones.

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

Calendario previsto

Se agrupan las convocatorias del mismo órgano con el mismo título sin años, fechas ni ediciones («XIV Premios X 2026» equivale a «XV Premios X 2027»). Las convocadas en tres o más años forman una serie con su fecha típica de registro y su variación. Se excluyen las nominativas, las directas y los convenios, que no se pueden solicitar.

Cada serie lleva una confianza (alta, media o baja) según los años que se ha convocado y lo regular que es su fecha. Baja un nivel si el año pasado se registró lejos de su fecha habitual, y no pasa de media si algún año no se convocó. La baja se oculta por defecto. Algunas series cambian de nombre o dejan de convocarse, así que la fecha prevista es una estimación. La herramienta calcula la evaluación con cada calendario y la muestra, para que la IA pueda decir cuánto fiarse.

El calendario necesita el histórico desde 2021. Se prepara en segundo plano la primera vez que se usa una herramienta de ayudas, no al arrancar, y entretanto ayudas_previstas avisa de que se está preparando en lugar de responder «no hay». La primera vez tarda alrededor de un minuto. Cada año se guarda en cuanto se descarga: si el cliente se cierra a medias, la siguiente vez se retoma con los años que faltaban. Al renovarse cada semana, solo se vuelve a descargar el año en curso, unos 20 segundos.

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

9. 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 y tipo se ignoran en silencio), así que 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, por lo que no las detecta todas. Los recuentos sin ese filtro las incluyen y lo advierten.
• 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 y puede tardar; repetido, sale de la caché.
• Calendario. Predice el registro en la BDNS, no el plazo de solicitud, y no detecta una ayuda que cambie de nombre.
• Comunidad. Una parte de las convocatorias no tiene 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.
• Lectura de PDF. Sin OCR y por reglas, no por IA.
• Varias instancias. El límite de una petición por segundo es por proceso: varios clientes abiertos a la vez suman su ritmo, aunque comparten la caché en disco.

10. 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

Datos y licencia

El código se distribuye con licencia MIT (ver LICENSE).

• 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. Origen de los datos: Agencia Estatal Boletín Oficial del Estado, mediante su API de datos abiertos. Se reutilizan según su aviso legal, que permite el uso comercial y no comercial citando la fuente, con enlace a boe.es, y sin sugerir su respaldo.
• Festivos. Nager.Date, API pública de festivos.

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.