Instalacion de MCP-Scan¶

Esta guia cubre todas las formas de instalar mcp-scan en tu sistema.

Tabla de Contenidos¶

Instalacion Rapida
Instalacion desde Binarios
Instalacion con Go
Compilacion desde Fuente
Instalacion con Docker
Verificacion de la Instalacion
Componentes Opcionales
Solucion de Problemas

Instalacion Rapida¶

Linux/macOS (Homebrew)¶

# Instalar via Homebrew (recomendado)
brew install mcphub/tap/mcp-scan

# Verificar instalacion
mcp-scan version

Windows (Scoop)¶

# Agregar bucket
scoop bucket add mcphub https://github.com/mcphub/scoop-bucket

# Instalar
scoop install mcp-scan

# Verificar instalacion
mcp-scan version

Instalacion desde Binarios¶

Descarga Manual¶

Ir a la pagina de releases:

https://github.com/mcphub/mcp-scan/releases/latest

Descargar el binario para tu plataforma:

Sistema	Arquitectura	Archivo
Linux	x86_64	`mcp-scan-linux-amd64.tar.gz`
Linux	ARM64	`mcp-scan-linux-arm64.tar.gz`
macOS	Intel	`mcp-scan-darwin-amd64.tar.gz`
macOS	Apple Silicon	`mcp-scan-darwin-arm64.tar.gz`
Windows	x86_64	`mcp-scan-windows-amd64.zip`

Extraer y mover al PATH:

Linux/macOS:

# Extraer
tar -xzf mcp-scan-linux-amd64.tar.gz

# Mover al PATH
sudo mv mcp-scan /usr/local/bin/

# Dar permisos de ejecucion
sudo chmod +x /usr/local/bin/mcp-scan

Windows (PowerShell):

# Extraer
Expand-Archive -Path mcp-scan-windows-amd64.zip -DestinationPath .

# Mover a un directorio en PATH
Move-Item mcp-scan.exe C:\Windows\System32\

Script de Instalacion Automatica¶

Linux/macOS:

curl -sSL https://raw.githubusercontent.com/mcphub/mcp-scan/main/install.sh | bash

Con version especifica:

curl -sSL https://raw.githubusercontent.com/mcphub/mcp-scan/main/install.sh | bash -s -- v2.0.0

Instalacion con Go¶

Si tienes Go 1.24+ instalado:

# Instalar ultima version
go install github.com/mcphub/mcp-scan/cmd/mcp-scan@latest

# Verificar que esta en el PATH
# Asegurate de que $GOPATH/bin esta en tu PATH
echo $PATH | grep -o 'go/bin'

# Si no esta, agregalo a tu .bashrc o .zshrc
export PATH=$PATH:$(go env GOPATH)/bin

Nota: Requiere Go 1.24 o superior debido a las dependencias de tree-sitter.

Compilacion desde Fuente¶

Requisitos¶

Go 1.24+
Git
Make (opcional, pero recomendado)
CGO habilitado (para tree-sitter)

Pasos¶

# Clonar repositorio
git clone https://github.com/mcphub/mcp-scan.git
cd mcp-scan

# Compilar con Make
make build

# O compilar directamente con Go
go build -o bin/mcp-scan ./cmd/mcp-scan

# Instalar en el sistema
sudo cp bin/mcp-scan /usr/local/bin/

Compilacion para Multiples Plataformas¶

# Linux AMD64
GOOS=linux GOARCH=amd64 go build -o bin/mcp-scan-linux-amd64 ./cmd/mcp-scan

# Linux ARM64
GOOS=linux GOARCH=arm64 go build -o bin/mcp-scan-linux-arm64 ./cmd/mcp-scan

# macOS AMD64
GOOS=darwin GOARCH=amd64 go build -o bin/mcp-scan-darwin-amd64 ./cmd/mcp-scan

# macOS ARM64 (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o bin/mcp-scan-darwin-arm64 ./cmd/mcp-scan

# Windows AMD64
GOOS=windows GOARCH=amd64 go build -o bin/mcp-scan-windows-amd64.exe ./cmd/mcp-scan

Instalacion con Docker¶

Imagen Oficial¶

# Descargar imagen
docker pull mcphub/mcp-scan:latest

# Ejecutar escaneo
docker run --rm -v $(pwd):/code mcphub/mcp-scan:latest scan /code

# Alias para uso frecuente
alias mcp-scan='docker run --rm -v $(pwd):/code mcphub/mcp-scan:latest'

Docker Compose¶

# docker-compose.yml
version: '3.8'
services:
  mcp-scan:
    image: mcphub/mcp-scan:latest
    volumes:
      - ./:/code:ro
      - ./results:/results
    command: scan /code --output json > /results/scan.json

Ejecutar:

docker-compose run mcp-scan

Construir Imagen Local¶

# Desde el directorio del proyecto
docker build -t mcp-scan:local .

# Ejecutar
docker run --rm -v $(pwd):/code mcp-scan:local scan /code

Verificacion de la Instalacion¶

Verificar Version¶

mcp-scan version

Salida esperada:

mcp-scan version 2.0.0
Build: 2026-01-23
Go: go1.24.0
OS/Arch: darwin/arm64

Verificar Funcionalidad¶

# Crear archivo de prueba
mkdir -p /tmp/mcp-test
cat > /tmp/mcp-test/server.py << 'EOF'
from mcp import tool

@tool
def run_command(cmd: str) -> str:
    """Executes a shell command"""
    import subprocess
    return subprocess.check_output(cmd, shell=True).decode()
EOF

# Ejecutar escaneo
mcp-scan scan /tmp/mcp-test

# Limpiar
rm -rf /tmp/mcp-test

Deberia detectar la vulnerabilidad de ejecucion de comandos (Clase A).

Verificar Integraciones Opcionales¶

# Verificar CodeQL (si esta instalado)
codeql version && echo "CodeQL disponible"

# Verificar Ollama (si esta instalado)
curl -s http://localhost:11434/api/tags && echo "Ollama disponible"

Componentes Opcionales¶

CodeQL (Confirmacion Secundaria)¶

CodeQL permite confirmar hallazgos con analisis estatico adicional.

Instalacion:

Descargar desde: https://github.com/github/codeql-cli-binaries/releases

Extraer y agregar al PATH:

# Linux/macOS
tar -xzf codeql-linux64.tar.gz
export PATH=$PATH:$(pwd)/codeql

# Verificar
codeql version

Configurar en mcp-scan:

# .mcp-scan.yaml
codeql:
  enabled: true
  cli_path: "/path/to/codeql"  # Opcional si esta en PATH

Ollama (Deteccion LLM)¶

Ollama permite usar modelos de lenguaje locales para deteccion semantica.

Instalacion:

# macOS/Linux
curl -fsSL https://ollama.com/install.sh | sh

# Iniciar servicio
ollama serve

# Descargar modelo recomendado
ollama pull llama3.2:3b

Configurar en mcp-scan:

# .mcp-scan.yaml
llm:
  enabled: true
  base_url: "http://localhost:11434"
  model: "llama3.2:3b"
  threshold: 0.7

Language Servers (LSP)¶

Los language servers mejoran la resolucion de tipos.

Python (Pyright):

npm install -g pyright

TypeScript:

npm install -g typescript typescript-language-server

Solucion de Problemas¶

Error: "command not found"¶

Causa: El binario no esta en el PATH.

Solucion:

# Verificar ubicacion
which mcp-scan

# Si no encuentra, verificar PATH
echo $PATH

# Agregar directorio al PATH (ejemplo)
export PATH=$PATH:/usr/local/bin

Error: "CGO_ENABLED=0 no soportado"¶

Causa: Tree-sitter requiere CGO.

Solucion:

# Compilar con CGO habilitado
CGO_ENABLED=1 go build -o mcp-scan ./cmd/mcp-scan

Error: "libtree-sitter.so not found"¶

Causa: Dependencias de tree-sitter no instaladas.

Solucion Linux:

# Ubuntu/Debian
sudo apt-get install build-essential

# Fedora/RHEL
sudo dnf install gcc gcc-c++ make

Solucion macOS:

xcode-select --install

Error de Permisos en Docker¶

Causa: El contenedor no tiene acceso al directorio.

Solucion:

# Usar flag --user
docker run --rm --user $(id -u):$(id -g) -v $(pwd):/code mcphub/mcp-scan:latest scan /code

Escaneo Muy Lento¶

Causa: Muchos archivos o modo deep sin cache.

Soluciones: 1. Usar modo fast para CI:

mcp-scan scan ./src --mode fast

Excluir directorios innecesarios:

# .mcp-scan.yaml
exclude:
  - "**/node_modules/**"
  - "**/venv/**"
  - "**/.git/**"

Aumentar workers:
```
mcp-scan scan ./src --workers 8
```

Memoria Insuficiente¶

Causa: Proyecto muy grande.

Soluciones: 1. Limitar archivos a analizar:

include:
  - "src/**/*.py"
  - "src/**/*.ts"

Usar modo fast:
```
mcp-scan scan ./src --mode fast
```

Actualizacion¶

Homebrew¶

brew upgrade mcp-scan

Go¶

go install github.com/mcphub/mcp-scan/cmd/mcp-scan@latest

Docker¶

docker pull mcphub/mcp-scan:latest

Manual¶

Repetir el proceso de instalacion con la nueva version.

Desinstalacion¶

Homebrew¶

brew uninstall mcp-scan

Manual¶

# Eliminar binario
sudo rm /usr/local/bin/mcp-scan

# Eliminar cache (opcional)
rm -rf ~/.mcp-scan

Docker¶

docker rmi mcphub/mcp-scan:latest

Siguiente: Inicio Rapido