MCP OSINT Server

MCP OSINT Server

Servidor MCP para agentes IA que permite ejecutar tareas OSINT de forma controlada, trazable y segura sobre una imagen Docker de Kali Linux.

Compatible con Claude Code, Gemini CLI y ChatGPT (mediante GPT Actions o function calling).

Arquitectura

[Claude Code / Gemini CLI / ChatGPT]
         |
         | MCP: stdio (local) / HTTP+SSE (remoto)
         v
[mcp_server/server.py]          Python, Anthropic MCP SDK
         |
         | HTTP → localhost:8001
         v
[osint_api/main.py]             FastAPI
         |
         v
[Docker Kali OSINT Sandbox]
    ├── whois, dig, subfinder, theHarvester, httpx, whatweb
    ├── sherlock, maigret, holehe, phoneinfoga
    ├── exiftool, mat2, pdfinfo, file, strings
    ├── gitleaks, trufflehog
    └── Conectores: AbuseIPDB, HIBP, EmailRep, VirusTotal, Shodan

Herramientas MCP disponibles (Fase 1 MVP)

Inicio rápido

Desarrollo local

# 1. Clonar y configurar
git clone <repo> mcp-osint-server
cd mcp-osint-server
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Configurar variables de entorno
cp config/.env.example config/.env
# Editar config/.env (al menos OSINT_INTERNAL_API_KEY)

# 3. Levantar la OSINT API
uvicorn osint_api.main:app --host 127.0.0.1 --port 8001 --reload

# 4. (En otra terminal) Probar el servidor MCP
source .venv/bin/activate
python -m mcp_server.server --transport stdio

Docker Compose (producción)

cp config/.env.example config/.env
# Editar config/.env

docker compose -f docker/docker-compose.yml up -d
# OSINT API en http://localhost:8001
# MCP Server (SSE) en http://localhost:3000/sse

Conectar a clientes IA

Ejemplo rápido — Claude Code (stdio)

Añade a ~/.claude/settings.json:

{
  "mcpServers": {
    "osint": {
      "command": "/ruta/al/proyecto/.venv/bin/python",
      "args": ["-m", "mcp_server.server", "--transport", "stdio"],
      "cwd": "/ruta/al/proyecto",
      "env": {
        "OSINT_API_URL": "http://127.0.0.1:8001",
        "OSINT_INTERNAL_API_KEY": "tu-clave",
        "OSINT_MODE": "safe"
      }
    }
  }
}

Tests

source .venv/bin/activate
pip install pytest pytest-asyncio
pytest tests/ -v

Variables de entorno

Seguridad

• Sin ejecución de comandos raw en modo safe.
• Allowlist estricta de binarios y argumentos CLI.
• Validación de todos los inputs antes de cualquier ejecución.
• Enmascarado de PII y API keys en outputs.
• Docker sandbox: no-new-privileges, cap_drop: ALL, read_only.
• Rate limiting por cliente y por API externa.
• Tool poisoning: resultados de internet se tratan como datos no confiables.

Estructura del proyecto

mcp-osint-server/
├── mcp_server/         # Servidor MCP (stdio + SSE)
│   ├── server.py       # Entry point, 13 herramientas MCP
│   └── schemas/        # Pydantic models compartidos
├── osint_api/          # FastAPI backend
│   ├── main.py
│   ├── runners/        # Ejecución segura de CLIs
│   ├── parsers/        # Parsers de output por herramienta
│   ├── connectors/     # APIs externas (AbuseIPDB, HIBP, etc.)
│   ├── workflows/      # 8 workflows OSINT
│   ├── catalog/        # Catálogo de herramientas
│   ├── security/       # Allowlist, validator, sanitizer, rate limiter
│   └── reports/        # Generadores Markdown/JSON/HTML
├── docker/             # Dockerfile.kali + docker-compose.yml
├── config/             # tools.yml, policies.yml, .env.example
├── docs/               # Documentación de conexión por cliente
└── tests/              # Tests unitarios

Roadmap

• Fase 1 (actual): MVP — 8 workflows, Docker Kali, catálogo, informes
• Fase 2: Autenticación, políticas por rol, cola de tareas, auditoría avanzada
• Fase 3: Correlación de entidades, grafo OSINT, scoring avanzado, STIX/TAXII

Licencia

Para uso en OSINT defensivo y autorizado únicamente. No usar para:doxxing, stalking, fuerza bruta, explotación activa o cualquier actividad ilegal.