🛡️ MCP Security Vision

Servidor MCP (Model Context Protocol) para videovigilancia inteligente en tiempo real: conecta cámaras de seguridad (IP por RTSP, analógicas por DVR o capturadora USB) con agentes de IA como Claude Desktop, Cursor, LangChain, AutoGen o tus propios bots.

YOLOv8 detecta objetos, face_recognition identifica personas conocidas y polígonos de intrusión vigilan zonas restringidas. Todo el historial se guarda en SQLite y se expone al agente como herramientas MCP.

_{Imagen generada por overlay.py con la cámara sintética (CAMERA_SOURCE=synthetic): objetos YOLO, rostro identificado y dos zonas restringidas, una de ellas en alerta (rojo).}

📚 Índice

• Características
• Novedades de la v2.0 / v2.1
• Arquitectura
• Instalación
• Configuración de cámaras
• Variables de entorno
• Conexión con agentes de IA
• Herramientas MCP
• Zonas restringidas
• Base de datos SQLite
• Docker
• GitHub Actions y Docker Hub
• Desarrollo y pruebas
• Seguridad y privacidad
• Problemas frecuentes
• Roadmap
• Publicar en GitHub
• Contribuir
• Licencia

✨ Características

🆕 Novedades de la v2.0 / v2.1

v2.1.0 es la revisión de seguridad y robustez: HTTP en loopback con validación de Host/Origin, cleanup_history con confirmación, esquema SQLite v2, backoff real de cámara, inferencia serializada y 144 tests. Ver CHANGELOG.md.

v2.0.1 corrige la guía de problemas frecuentes tras verificarla contra el código (mensajes de consola reales, RTSP_TRANSPORT, FACE_MODEL, validación de YOLO_IMGSZ, comprobación de puerto antes de cargar modelos) y añade los scripts de publicación. Ver CHANGELOG.md.

La v2.0 incorporó las extensiones solicitadas:

1. Base de datos SQLite para historial permanente (mcp_security_vision/database.py)
   • Tablas events, zones, people, índices y WAL para escrituras concurrentes.
   • Herramientas get_security_report, filtros por horas/tipo y cleanup_history con retención.
2. GitHub Actions para pruebas y publicación en Docker Hub
   • .github/workflows/ci.yml: lint + tests + smoke test del contenedor.
   • .github/workflows/docker-publish.yml: build multi-arquitectura (amd64/arm64) y push con tags semánticos.
3. Zonas restringidas (polígonos de intrusión) (mcp_security_vision/zones.py)
   • Detección punto-en-polígono, tracker por IoU para no duplicar eventos, dwell time y evidencia fotográfica.
   • Herramientas MCP add_restricted_zone, list_restricted_zones, remove_restricted_zone, get_active_intrusions.

Y de la hoja de ruta v2.0 original:

1. Soporte multicámara con CAMERAS en JSON y camera_id en todas las herramientas.
2. Arquitectura desacoplada (paquete mcp_security_vision/), lista para combinarse con otros servidores MCP (Telegram, WhatsApp, Notion…) sin tocar el código de visión, más webhook opcional para reaccionar a alertas.

🏗️ Arquitectura

                    ┌──────────────────────────────┐
   Claude Desktop   │                              │
   Cursor / Cline ──┤        Servidor MCP          │
   LangChain/AutoGen│  server.py  (13 tools + 1    │
   HTTP / Docker ───┤  recurso security://status)  │
                    └──────────────┬───────────────┘
                                   │  (mismo proceso, sin bloqueo)
                    ┌──────────────▼───────────────┐
                    │        VisionSystem          │
                    │  cámaras · zonas · registro  │
                    └──────┬─────────────┬─────────┘
        ┌──────────────────┼─────────────┼──────────────────┐
        ▼                  ▼             ▼                  ▼
 ┌────────────┐    ┌─────────────┐  ┌──────────┐    ┌────────────┐
 │ CameraWorker│   │  Pipeline   │  │  SQLite  │    │ Snapshots  │
 │ (1 hilo por │   │ YOLO → IoU  │  │ events   │    │  alertas   │
 │  cámara)    │   │ → caras →   │  │ zones    │    │  .jpg      │
 │ reconexión  │   │ zonas → log │  │ people   │    │ retención  │
 └────────────┘    └─────────────┘  └──────────┘    └────────────┘
        │                  │
        │                  └─────► Webhook JSON (opcional)
        └── RTSP · USB · DVR · synthetic

Estructura del repositorio

mcp-security-vision/
├── mcp_security_vision/          # Paquete instalable
│   ├── server.py                 # Herramientas MCP + arranque (compat. SDK 1.x/2.x)
│   ├── system.py                 # Fachada de negocio (lo que usan las tools)
│   ├── camera.py                 # Hilo por cámara + reconexión + estado
│   ├── pipeline.py               # Detección → tracking → caras → zonas → eventos
│   ├── detectors.py              # YOLOv8 + utilidades de cajas
│   ├── faces.py                  # Registro y reconocimiento facial
│   ├── zones.py                  # Polígonos de intrusión + monitor
│   ├── tracker.py                # Tracker IoU (IDs estables)
│   ├── database.py               # SQLite: eventos, zonas, personas
│   ├── snapshots.py              # Evidencias JPEG y retención
│   ├── overlay.py                # Dibujo de cajas, rostros y zonas
│   ├── notifications.py          # Webhook opcional en segundo plano
│   ├── synthetic.py              # Cámara sintética para demos/CI
│   ├── fakes.py                  # Modelos simulados (CI, sin torch ni dlib)
│   └── config.py                 # Settings desde .env (+ multicámara JSON)
├── config/zones.example.json     # Zonas iniciales (seed)
├── known_faces/                  # Fotos de personas conocidas (nombre_apellido.jpg)
├── snapshots/                    # Evidencias generadas
├── data/                         # security.db (SQLite)
├── docs/
│   ├── TROUBLESHOOTING.md        # Problemas frecuentes (verificados con tests)
│   ├── PUBLICAR_EN_GITHUB.md     # Cómo subir el repo (manual, gh, script, agente)
│   └── demo_annotated.jpg        # Captura anotada de ejemplo
├── scripts/
│   ├── check_setup.py            # Diagnóstico de instalación
│   ├── draw_zones.py             # Editor visual de polígonos
│   ├── configure_repo.py         # Quita placeholders antes de publicar
│   └── publish_github.sh         # Push seguro con verificación de secretos
├── tests/                        # 144 tests (unitarios + integración MCP)
├── .github/workflows/            # ci.yml + docker-publish.yml
├── .github/ISSUE_TEMPLATE/       # plantillas de bug y propuesta
├── SECURITY.md · CONTRIBUTING.md # política de seguridad y guía de contribución
├── server.py                     # Atajo: python server.py
├── Dockerfile · docker-compose.yml · Makefile
├── requirements.txt · requirements-dev.txt · pyproject.toml
└── .env.example

🚀 Instalación

Requisitos

• Python 3.10, 3.11 o 3.12 (dlib todavía no soporta 3.13+)
• cmake y compilador C++ (para dlib, que usa face-recognition)
  • Debian/Ubuntu: sudo apt install build-essential cmake libopenblas-dev liblapack-dev libgl1
  • macOS: brew install cmake
  • Windows: Visual Studio Build Tools con la carga de trabajo Desarrollo para el escritorio con C++ + CMake
• Opcional: GPU NVIDIA con CUDA para acelerar YOLO (YOLO_DEVICE=0)

Pasos

git clone https://github.com/kfr0st/mcp-security-vision.git
cd mcp-security-vision

python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate

pip install -r requirements.txt
cp .env.example .env              # configura tus cámaras y rutas
python scripts/check_setup.py --read-frames

¿Sin cámara a mano? Prueba todo el flujo con la cámara sintética y modelos simulados:

VISION_FAKE_MODELS=1 CAMERA_SOURCE=synthetic python server.py --transport streamable-http --host 127.0.0.1

O simplemente make demo.

Instalación como paquete (opcional)

pip install ".[vision]"     # código + YOLO + dlib
mcp-security-vision --check # comando instalado

📷 Configuración de cámaras

Todo se define en .env (nunca en el código). Ver .env.example para la lista completa.

Una sola cámara

# Webcam o capturadora USB (índice del dispositivo)
CAMERA_SOURCE=0

# Cámara IP / DVR por RTSP
# CAMERA_SOURCE=rtsp://usuario:clave@192.168.1.50:554/Streaming/Channels/101

Varias cámaras

CAMERAS={"entrada": "rtsp://admin:clave@192.168.1.50:554/Streaming/Channels/101", "patio": 0, "demo": "synthetic"}

# O con nombres visibles y cámaras deshabilitadas:
# CAMERAS=[{"id":"entrada","name":"Puerta principal","source":"rtsp://..."},
#          {"id":"patio","name":"Patio trasero","source":0},
#          {"id":"cochera","name":"Cochera","source":2,"enabled":false}]

Todas las herramientas aceptan camera_id; si se omite se usa la primera cámara habilitada.

URLs RTSP habituales

🎥 Cámaras analógicas (coaxial/BNC): sin cambiar una línea de código.

1. Vía DVR/XVR (recomendado): conecta el DVR al router y usa su RTSP por canal.
2. Vía capturadora RCA/BNC → USB (~10 USD): el sistema la ve como webcam CAMERA_SOURCE=0/1.

⚙️ Variables de entorno principales

🤖 Conexión con agentes de IA

Claude Desktop / Cursor (transporte stdio)

Edita claude_desktop_config.json (~/Library/Application Support/Claude/ en macOS, %APPDATA%\Claude\ en Windows) y añade:

{
  "mcpServers": {
    "security-camera": {
      "command": "/ruta/absoluta/a/mcp-security-vision/venv/bin/python",
      "args": ["/ruta/absoluta/a/mcp-security-vision/server.py"],
      "env": {
        "CAMERA_SOURCE": "rtsp://usuario:clave@192.168.1.50:554/Streaming/Channels/101"
      }
    }
  }
}

En Windows usa C:\\ruta\\...\\venv\\Scripts\\python.exe. Los logs del servidor van a stderr, así que no rompen el protocolo stdio.

Clientes HTTP (Docker, remoto, agentes web)

docker compose up -d --build          # endpoint: http://localhost:8000/mcp
# o en local (solo accesible desde tu máquina):
python server.py --transport streamable-http --host 127.0.0.1 --port 8000

Ejemplo mínimo con el SDK oficial de Python:

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client


async def main():
    async with streamablehttp_client("http://localhost:8000/mcp") as streams:
        read, write = streams[0], streams[1]  # 3 valores en SDK 1.x, 2 en SDK 2.x
        async with ClientSession(read, write) as session:
            await session.initialize()
            status = await session.call_tool("get_live_status", {})
            print(status.content[0].text)


asyncio.run(main())

El SDK 2.x renombró algunas funciones; el servidor incluye un shim para funcionar con MCP SDK 1.x y 2.x sin cambios.

Prompts de ejemplo

• «¿Hay alguien en la entrada ahora mismo? ¿Es alguien conocido?»
• «Toma una captura anotada del patio y dime si el repartidor dejó un paquete en el suelo.»
• «Revisa los registros de las últimas 24 horas y dime a qué hora pasó Carlos.»
• «Define una zona restringida llamada "Caja fuerte" con el polígono [[0.6,0.4],[0.95,0.4],[0.95,0.9],[0.6,0.9]] en cam1.»
• «¿Hay alguna intrusión activa en este momento?»
• «Estoy frente a la cámara: regístrame como "Administrador".»

🧰 Herramientas MCP

Eventos registrados (event_type)

intrusion · face_known · face_unknown · person_unidentified · camera_online · camera_offline · face_registered · face_forgotten · zone_added · zone_removed · system

🚧 Zonas restringidas (intrusión)

Las coordenadas son normalizadas (0..1) respecto al ancho y alto de la imagen: (0,0) = esquina superior izquierda, (1,1) = inferior derecha. Así la zona funciona con 720p, 1080p o 4K y sobrevive a reconexiones.

[
  [0.35, 0.30],
  [0.65, 0.30],
  [0.65, 0.95],
  [0.35, 0.95]
]

Cómo crear zonas

1. Pidiéndoselo al agente (herramienta add_restricted_zone).
2. Con el editor visual (recomendado para ajustar a mano):

   python scripts/draw_zones.py --camera-id cam1 --name "Puerta trasera" --labels person,car
   # clic = vértice · u = deshacer · c = limpiar · s = guardar
   

3. Con el archivo semilla config/zones.example.json (se importa al arrancar si la zona no existe).

Mecánica anti-spam

• El tracker asigna un ID estable (#1, #2…) a cada objeto; solo se registra una intrusión por entrada.
• Al salir de la zona (sin detección durante PRESENCE_TIMEOUT_SECONDS) se libera el estado, y una nueva entrada vuelve a alertar (respetando INTRUSION_COOLDOWN_SECONDS).
• Cada intrusión guarda una captura de evidencia y se acompaña de dwell_seconds (tiempo dentro).

🗄️ Base de datos SQLite

Archivo: data/security.db (WAL activado para escrituras concurrentes desde varios hilos de cámara).

-- Esquema resumido
events(id, camera_id, created_at, event_type, severity, description,
       object_label, track_id, zone_names, snapshot_path, metadata)
zones(id, camera_id, name, points, labels, enabled, created_at, updated_at)
people(id, name, slug, file_name, created_at, updated_at)

Consultas útiles:

-- ¿Quién pasó hoy?
SELECT created_at, description FROM events
WHERE event_type = 'face_known' AND created_at >= date('now', 'start of day');

-- Intrusiones por zona en los últimos 7 días
SELECT zone_names, COUNT(*) FROM events
WHERE event_type = 'intrusion' AND created_at >= datetime('now', '-7 days')
GROUP BY zone_names;

-- Agenda de presencia por persona
SELECT json_extract(metadata, '$.person') AS persona, MIN(created_at), MAX(created_at), COUNT(*)
FROM events WHERE event_type = 'face_known' GROUP BY persona;

Las marcas de tiempo son hora local del servidor en ISO-8601 (YYYY-MM-DDTHH:MM:SS), ordenables como texto.

Respaldo: copia data/security.db (con WAL, usa sqlite3 data/security.db ".backup copia.db"). Retención: cleanup_history(keep_days=90, confirm=true); añade purge_snapshots=true para borrar también las capturas. Sin confirm=true la herramienta solo describe lo que haría.

🐳 Docker

# 1. Configura el entorno
cp .env.example .env

# 2. Construye y levanta (endpoint MCP en http://localhost:8000/mcp)
docker compose up -d --build
docker compose logs -f

# 3. Prueba rápida sin cámara (modo demo)
docker run --rm -p 127.0.0.1:8000:8000 -e VISION_FAKE_MODELS=1 -e CAMERA_SOURCE=synthetic \
  kfr0st/mcp-security-vision:latest

• Imagen multi-stage (dlib se compila en el builder; la imagen final no lleva compiladores).
• Corre como usuario no-root (vision).
• Volúmenes: data (SQLite), snapshots, known_faces, config, yolo-models (pesos persistentes).
• Para cámara USB en Linux añade devices: ["/dev/video0:/dev/video0"] y group_add: ["video"].
• Por defecto solo se aceptan hosts locales (localhost, 127.0.0.1, [::1] y sus puertos). Si publicas detrás de un proxy, añade tu dominio a MCP_ALLOWED_HOSTS (por ejemplo, MCP_ALLOWED_HOSTS=mcp.midominio.com,mcp.midominio.com:*) y define MCP_ALLOWED_ORIGINS=https://mcp.midominio.com si usas un navegador.
• El transporte HTTP no trae autenticación. No lo expongas directamente a Internet: usa un proxy con TLS y autenticación, o una red privada/VPN.
• PRELOAD_MODELS=true (build-arg) incluye yolov8n.pt en la imagen para despliegues sin Internet.
• El contenedor corre como UID 1000. Si usas bind mounts en Linux y ves Permission denied: sudo chown -R 1000:1000 data snapshots known_faces (o usa volúmenes nombrados).

🔁 GitHub Actions y Docker Hub

CI (.github/workflows/ci.yml)

Se ejecuta en cada push y pull request:

1. Lint: ruff check + ruff format --check.
2. Tests: matriz Python 3.10 / 3.11 / 3.12 × MCP SDK 1.x / 2.x, con VISION_FAKE_MODELS=1 (sin torch ni dlib → CI en ~1 min), cobertura y JUnit XML.
3. Smoke test Docker: construye la imagen, arranca el contenedor en modo demo y espera a que abra el puerto 8000.

Publicación en Docker Hub (.github/workflows/docker-publish.yml)

Se dispara con tags v*.*.*, pushes a main o manualmente. Construye linux/amd64 + linux/arm64 y publica:

Configuración (una sola vez)

1. Crea un repositorio en Docker Hub: kfr0st/mcp-security-vision.
2. Genera un Access Token en Docker Hub → Account settings → Security.
3. En GitHub → Settings → Secrets and variables → Actions, añade:
   • DOCKERHUB_USERNAME
   • DOCKERHUB_TOKEN
   • (opcional) DOCKERHUB_REPO si el repo no se llama mcp-security-vision.
4. Publica:

   git tag v2.1.0 && git push origin v2.1.0
   

Si faltan los secrets, el workflow solo hace build (con un warning) y no falla.

🧪 Desarrollo y pruebas

pip install -r requirements-dev.txt      # sin torch/dlib
pip install --no-deps -e .

make test      # pytest + cobertura (144 tests, ~25 s)
make lint      # ruff check
make format    # ruff format + fixes
make demo      # servidor con cámara sintética y modelos falsos
make check     # valida .env y rutas

Qué cubren los tests:

• Parseo de configuración (multicámara, validaciones, enmascarado de credenciales).
• SQLite: eventos, filtros temporales, resúmenes, zonas, personas y persistencia.
• Geometría de polígonos + monitor de intrusiones (entrada, dwell, reentrada, etiquetas).
• Tracker IoU, estabilizador de nombres, registro/reconocimiento facial (con backend falso).
• Pipeline completo con detectores simulados y evidencias JPEG.
• Webhook de notificaciones contra un servidor HTTP local.
• Integración MCP real: levanta server.py en un subproceso, lista herramientas, llama a get_live_status, add_restricted_zone, get_security_logs, capture_snapshot (verifica JPEG) y el recurso security://status.

server.py se ejecuta en un subproceso durante los tests, por eso la cobertura global (~81 %) es menor que la de los módulos de lógica (~90 %); el arranque está cubierto end-to-end por el test de integración.

🔒 Seguridad y privacidad

• Las contraseñas de cámaras viven solo en .env (ignorado por git) o en variables de entorno.
• Los logs muestran las URLs con la clave y los tokens de la query enmascarados (rtsp://admin:***@...).
• known_faces/, snapshots/ y data/ están en .gitignore: no subas fotos de personas al repo.
• Recomendado: usuarios RTSP de solo lectura y contraseñas fuertes; segmenta las cámaras en una VLAN.
• El reconocimiento facial biométrico es dato sensible: informa a las personas y cumple tu normativa local (GDPR/RGPD, LFPDPPP, Ley 29733 en Perú, etc.).
• En Docker el proceso corre sin privilegios y con no-new-privileges.
• El transporte HTTP escucha en loopback y valida Host/Origin por defecto, pero no incluye autenticación: si lo expones, ponlo detrás de HTTPS + autenticación y limita MCP_ALLOWED_HOSTS.
• cleanup_history exige confirm=true y no borra capturas salvo que pidas purge_snapshots=true.

Checklist para producción

• MCP_HOST=127.0.0.1 o proxy con TLS y autenticación.
• MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS ajustados a tu dominio real.
• .env fuera de git y con permisos restringidos (chmod 600).
• Usuario RTSP de solo lectura y cámaras en una VLAN segmentada.
• Retención definida (cleanup_history) y copias de seguridad de data/security.db.
• Aviso de privacidad y base legal para las personas grabadas.
• Contenedor como usuario no-root y volúmenes con permisos mínimos.
• Dependencias auditadas (pip-audit, Dependabot) y tokens rotados.

🩺 Problemas frecuentes

Guía completa y verificada ejecutando el código: docs/TROUBLESHOOTING.md. Cada fila está cubierta por tests (tests/test_troubleshooting.py), así que no se queda desfasada.

🗺️ Roadmap

• Tracking con ByteTrack/BoTSORT para oclusiones y multitudes.
• Embeddings en SQLite (evitar re-calcular rostros al arrancar) y cifrado en reposo.
• Panel web (FastAPI + HTMX) con stream anotado y mapa de zonas.
• Notificaciones nativas a Telegram/WhatsApp como MCP aparte o plugin.
• Zonas por horario («solo de 22:00 a 06:00») y reglas de dirección (entrar vs. salir).
• Exportación de clips MP4 alrededor de cada alerta.
• Autenticación OAuth para el transporte HTTP.

📤 Publicar en GitHub

Guía paso a paso (manual, con gh, con script y prompt listo para el agente de opencode): docs/PUBLICAR_EN_GITHUB.md

# 1) personaliza badges/URLs/autor con tus datos
python scripts/configure_repo.py --github-user kfr0st --name "kfr0st"

# 2) publica (aborta si detecta .env, *.db, *.pt o fotos de known_faces/)
bash scripts/publish_github.sh git@github.com:kfr0st/mcp-security-vision.git

🤝 Contribuir

Lee CONTRIBUTING.md para el entorno de desarrollo, estilo y comprobaciones antes del PR. Para vulnerabilidades usa el reporte privado de SECURITY.md; no abras un issue público.

1. Haz fork y crea una rama: git checkout -b feature/mi-mejora.
2. make lint && make test en verde.
3. Pull request describiendo el cambio y, si aplica, nuevos tests.

📄 Licencia

MIT © 2026 kfr0st. Ver LICENSE.

Hecho con ❤️ para la comunidad MCP hispanohablante · modelcontextprotocol.io