BDNS MCP Server

Servidor MCP (Model Context Protocol) para buscar ayudas y subvenciones públicas españolas usando la API del Sistema Nacional de Publicidad de Subvenciones y Ayudas Públicas (BDNS).

Características

• 🔍 Búsqueda de ayudas con múltiples filtros

• 📋 Consulta de detalles completos de convocatorias

• 🆕 Listado de últimas ayudas publicadas

• 🗺️ Catálogo de regiones y tipos de beneficiario

• ⚡ Rate limiting automático (1 req/s)

• 🔄 Retry con backoff exponencial

• 🎯 Cache de regiones para búsquedas rápidas

Related MCP server: Catalunya Open Data MCP

Instalación

Requisitos

• Python 3.10 o superior

• pip

Instalar desde el código fuente

# Clonar o descargar el repositorio
cd bdns-mcp

# Instalar en modo desarrollo
pip install -e .

# O instalar con dependencias de desarrollo
pip install -e ".[dev]"

Configuración en Claude Desktop

Edita tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Añade la siguiente configuración:

{
  "mcpServers": {
    "bdns": {
      "command": "python",
      "args": ["-m", "bdns_mcp.server"]
    }
  }
}

Si has instalado en un entorno virtual, especifica la ruta completa al Python del entorno:

{
  "mcpServers": {
    "bdns": {
      "command": "/ruta/a/tu/venv/bin/python",
      "args": ["-m", "bdns_mcp.server"]
    }
  }
}

Reinicia Claude Desktop para aplicar los cambios.

Herramientas Disponibles

1. buscar_ayudas

Busca convocatorias de ayudas con filtros.

Parámetros:

• texto (opcional): Texto a buscar en el título

• tipo_busqueda (opcional): 0=frase exacta, 1=todas las palabras, 2=alguna palabra (default: 2)

• comunidad (opcional): Nombre de comunidad autónoma (ej: "ARAGÓN", "CATALUÑA")

• tipo_beneficiario (opcional): "persona_fisica", "persona_juridica", "pyme", "autonomo", "gran_empresa"

• tipo_administracion (opcional): "estatal", "autonomica", "local", "otros"

• fecha_desde (opcional): Fecha inicio formato DD/MM/YYYY

• fecha_hasta (opcional): Fecha fin formato DD/MM/YYYY

• solo_abiertas (opcional): Solo convocatorias abiertas (default: false)

• max_resultados (opcional): Máximo resultados (default: 10, max: 50)

Ejemplo de uso:

Usuario: ¿Qué ayudas hay para autónomos en Aragón?
Claude: [usa buscar_ayudas con tipo_beneficiario="autonomo" y comunidad="ARAGÓN"]

2. detalle_ayuda

Obtiene información completa de una convocatoria.

Parámetros:

• codigo_bdns (requerido): Código BDNS de la convocatoria

Ejemplo:

Usuario: Dame más detalles de la ayuda 789012
Claude: [usa detalle_ayuda con codigo_bdns="789012"]

3. ultimas_ayudas

Lista las últimas convocatorias publicadas.

Parámetros:

• comunidad (opcional): Filtrar por comunidad autónoma

• max_resultados (opcional): Máximo resultados (default: 10, max: 20)

4. listar_regiones

Devuelve el catálogo completo de regiones disponibles.

5. listar_tipos_beneficiario

Devuelve los tipos de beneficiario disponibles.

Ejemplos de Uso

Búsqueda simple

Usuario: Busca ayudas para digitalización

Claude usa: buscar_ayudas(texto="digitalización")

Búsqueda con filtros

Usuario: Ayudas para pymes en Cataluña con plazo abierto

Claude usa: buscar_ayudas(
    tipo_beneficiario="pyme",
    comunidad="CATALUÑA",
    solo_abiertas=true
)

Consultar detalles

Usuario: Dame detalles de la convocatoria 654321

Claude usa: detalle_ayuda(codigo_bdns="654321")

Últimas ayudas

Usuario: ¿Cuáles son las últimas ayudas publicadas en Madrid?

Claude usa: ultimas_ayudas(comunidad="MADRID")

Tipos de Beneficiario

• persona_fisica: Personas físicas que no desarrollan actividad económica

• persona_juridica: Personas jurídicas que no desarrollan actividad económica

• pyme: PYME y personas físicas que desarrollan actividad económica (incluye autónomos)

• autonomo: Alias para "pyme"

• gran_empresa: Gran empresa

• sin_especificar: Sin información específica

Tipos de Administración

• estatal: Administración del Estado

• autonomica: Comunidad Autónoma

• local: Entidad Local

• otros: Otros órganos

API de Referencia

Este servidor utiliza la API pública del BDNS:

• Base URL: https://www.infosubvenciones.es/bdnstrans/api

• Documentación: https://www.infosubvenciones.es/bdnstrans/doc/swagger

Desarrollo

Ejecutar tests

pytest tests/

Estructura del Proyecto

bdns-mcp/
├── pyproject.toml
├── README.md
├── ESPECIFICACION.md
├── src/
│   └── bdns_mcp/
│       ├── __init__.py
│       ├── server.py          # MCP server principal
│       ├── api_client.py      # Cliente HTTP para BDNS
│       ├── models.py          # Modelos Pydantic
│       └── catalogos.py       # Mapeos y catálogos
└── tests/
    └── test_api.py

Limitaciones y Consideraciones

• La API pública del BDNS no requiere autenticación

• Rate limiting implementado: 1 petición por segundo

• Retry automático con backoff exponencial en caso de errores

• Cache de regiones para optimizar búsquedas

• Encoding UTF-8 para manejar caracteres especiales

Licencia

MIT

Contribuir

Las contribuciones son bienvenidas. Por favor, abre un issue o pull request.

Soporte

Para problemas o preguntas, abre un issue en el repositorio.