SECOP MCP Server
<!-- mcp-name: io.github.juandavidsernav/secop-mcp-server -->Servidor MCP (Model Context Protocol) para consultar la contratación pública de Colombia a través de SECOP I y SECOP II.
Los datos se obtienen en tiempo real desde datos.gov.co (API SODA de Socrata) y son 100% públicos. No se almacena ningún dato localmente.
¿Para qué sirve?
Este servidor permite que modelos de lenguaje como Claude consulten directamente los datos de contratación pública del Estado colombiano. Esto facilita:
- Control político: Investigar contratos de entidades públicas y funcionarios.
- Transparencia: Verificar contratistas, montos y modalidades de contratación.
- Periodismo de datos: Cruzar información de proveedores y entidades.
- Veeduría ciudadana: Cualquier persona puede consultar cómo se gastan los recursos públicos.
Datasets disponibles
| Dataset | Descripción | Fuente |
|---|---|---|
| SECOP I - Procesos | Datos históricos de procesos de compra pública | datos.gov.co |
| SECOP II - Procesos | Procesos de contratación transaccionales | datos.gov.co |
| SECOP II - Contratos | Contratos electrónicos con valores pagados/facturados | datos.gov.co |
| SECOP II - Proveedores | Proveedores registrados en la plataforma | datos.gov.co |
Herramientas (Tools)
| Tool | Descripción |
|---|---|
buscar_secop1 | Buscar procesos en SECOP I por entidad, contratista, objeto, departamento, rango de fechas, etc. |
buscar_procesos_secop2 | Buscar procesos de contratación en SECOP II con filtros temporales |
buscar_contratos_secop2 | Buscar contratos electrónicos en SECOP II con filtros temporales |
buscar_proveedores | Buscar proveedores registrados en SECOP II |
buscar_por_persona | Buscar en TODOS los datasets por cédula/NIT o nombre de una persona |
resumen_contratacion | Vista condensada de contratos (campos clave: entidad, proveedor, valor, estado, fecha) |
agregaciones_contratacion | Totales agrupados por proveedor, entidad, departamento o modalidad |
consulta_libre | Consulta SoQL avanzada sobre cualquier dataset |
listar_datasets | Ver todos los datasets y sus campos disponibles |
Instalación
Requisitos
- Python 3.11+
- uv (recomendado) o pip
Opción 1: Desde PyPI (recomendada)
# Con uv (más rápido)
uvx secop-mcp-server
# Con pip
pip install secop-mcp-server
Opción 2: Desde GitHub
uvx --from git+https://github.com/juandavidsernav/secop-mcp-server secop-mcp
Opción 3: Desde el código fuente
git clone https://github.com/juandavidsernav/secop-mcp-server.git
cd secop-mcp-server
uv sync
Configuración
Claude Code
# Instalación rápida desde PyPI
claude mcp add secop-colombia -- uvx secop-mcp-server
# O desde código fuente
claude mcp add secop-colombia -- uv run --directory /ruta/al/secop-mcp-server secop-mcp
Claude Desktop
Edita el archivo de configuración:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"secop-colombia": {
"command": "uvx",
"args": ["secop-mcp-server"]
}
}
}
App Token (opcional pero recomendado)
Sin token funciona, pero con rate-limiting agresivo (~60 peticiones/hora). Obtén uno gratis:
- Regístrate en datos.gov.co
- Ve a tu perfil > Developer Settings
- Crea un nuevo App Token
Configúralo como variable de entorno:
{
"mcpServers": {
"secop-colombia": {
"command": "uvx",
"args": ["secop-mcp-server"],
"env": {
"SOCRATA_APP_TOKEN": "tu-token-aqui"
}
}
}
}
Ejemplos de uso
Una vez configurado, puedes pedirle a Claude cosas como:
- "Busca los contratos de la Alcaldía de Bogotá por más de 1000 millones"
- "¿Qué contratos tiene la persona con cédula 12345678?"
- "Muestra los procesos de licitación pública en Antioquia"
- "¿Cuáles son los contratos más grandes de SECOP II este año?"
- "Busca todos los contratos asociados a la empresa XYZ"
- "¿Cuánto ha contratado el municipio de Medellín en prestación de servicios?"
- "Dame un resumen de los contratos de EPM en 2024"
- "¿Cuáles son los proveedores con más contratos en Antioquia?"
- "Agrupa por modalidad los contratos de la Alcaldía de Medellín"
- "Muestra los contratos firmados entre enero y marzo de 2025 en el Valle del Cauca"
Estructura del proyecto
secop-mcp-server/
├── secop_mcp/
│ ├── __init__.py # Documentación del paquete
│ ├── server.py # Servidor MCP y definición de herramientas (tools)
│ ├── client.py # Cliente HTTP para la API SODA de Socrata
│ └── datasets.py # Catálogo de datasets SECOP y sus metadatos
├── pyproject.toml # Configuración del paquete Python
├── LICENSE # Licencia MIT
└── README.md # Este archivo
¿Cómo funciona?
Claude (LLM) <--MCP/stdio--> secop-mcp-server <--HTTP/SoQL--> datos.gov.co (API SODA)
- Claude invoca una herramienta MCP (ej:
buscar_contratos_secop2). - El servidor construye una consulta SoQL con los filtros proporcionados.
- Se ejecuta la petición HTTP a la API de datos.gov.co.
- Los resultados se formatean en texto legible y se retornan a Claude.
- Claude analiza los datos y responde al usuario.
Todo corre localmente en tu máquina. No hay servidor intermedio ni se almacenan datos.
Contribuir
Las contribuciones son bienvenidas:
- Fork del repositorio
- Crea una rama para tu feature (
git checkout -b feature/nueva-funcionalidad) - Commit de tus cambios (
git commit -m 'Agrega nueva funcionalidad') - Push a la rama (
git push origin feature/nueva-funcionalidad) - Abre un Pull Request
Ideas para contribuir
- Agregar más datasets de datos.gov.co
- Traducciones del README
- Alertas o monitoreo de nuevos contratos
- Exportación a CSV/Excel
Licencia
MIT - Libre para uso personal, comercial, modificación y redistribución.