BDNS 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

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.