DesktopCommanderPy

Servidor MCP propio en Python — alternativa segura, extensible y 100% tuya a Desktop Commander.

¿Qué es esto?

DesktopCommanderPy es un servidor Model Context Protocol (MCP) escrito completamente en Python que da a Claude (o cualquier IA compatible con MCP) acceso controlado a tu máquina local y a tus sistemas externos.

Módulos actuales:

• Filesystem — lectura, escritura, búsqueda, edición quirúrgica

• Terminal — ejecución de comandos bloqueantes y streaming

• Procesos — gestión con psutil y sesiones interactivas (REPLs)

• SAP HANA Cloud — conexión, consultas, administración vía hdbcli

Construido como alternativa personal a Desktop Commander:

• Control total — cada línea de código es tuya, sin cajas negras

• Seguridad desde el principio — sandbox de rutas, blacklist de comandos, credenciales por variables de entorno

• Extensible — añadir un módulo nuevo es copiar un fichero y registrar las tools en server.py

• Multiplataforma — Windows (PowerShell) primario, Linux/macOS con detección automática

Related MCP server: filesystem_sandbox

Estado actual

Estructura del proyecto

DesktopCommanderPy/
├── main.py                          # Entry point: stdio o HTTP/SSE
├── pyproject.toml                   # Dependencias, build con hatchling
├── config/
│   ├── security_config.yaml         # Sandbox: dirs, blacklist, límites
│   ├── hana_config.yaml             # Credenciales HANA (NO en git, ver .gitignore)
│   └── hana_config.yaml.example     # Plantilla de configuración HANA
├── core/
│   ├── server.py                    # FastMCP + registro de las 28 tools
│   └── tools/
│       ├── filesystem.py            # 9 tools de sistema de archivos
│       ├── terminal.py              # 2 tools de terminal
│       ├── process.py               # 2 tools de procesos (psutil)
│       ├── process_sessions.py      # 5 tools de sesiones interactivas
│       ├── session_manager.py       # SessionManager con asyncio.Queue
│       ├── hana.py                  # 8 tools SAP HANA Cloud
│       └── utils.py                 # Seguridad, config, plataforma
└── tests/
    └── test_basic.py                # 15 tests: seguridad, filesystem, stdio

Instalación

cd C:\Users\Edu\DesktopCommanderPy
py -3.12 -m venv .venv
.venv\Scripts\activate
pip install -e .
pip install hdbcli              # módulo SAP HANA Cloud
pip install pytest pytest-asyncio   # solo para tests

Configuración de seguridad

config/security_config.yaml:

security:
  allowed_directories:
    - "C:/Users/Edu/Documents"
    - "C:/Users/Edu/Desktop"
    - "C:/Users/Edu/DesktopCommanderPy"
    - "C:/Users/Edu/VerbaSant"
    # añadir más según necesidad

  blocked_commands:
    - "format"
    - "diskpart"
    - "net user"
    - "reg add"
    - "reg delete"
    - "shutdown"

  write_blocked_extensions: [".exe", ".dll", ".sys"]
  max_file_size_bytes: 10485760
  max_read_lines: 2000

terminal:
  default_timeout_seconds: 30
  max_output_chars: 500000

⚠️ Si allowed_directories está vacío, el sandbox está desactivado.

Arrancar el servidor

py main.py                        # stdio — Claude Desktop
py main.py --http --port 8080     # HTTP/SSE — clientes remotos
py main.py --log-level DEBUG      # con logs detallados

Configurar en Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "DesktopCommanderPy": {
      "command": "C:\\Users\\Edu\\DesktopCommanderPy\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\Edu\\DesktopCommanderPy\\main.py"],
      "env": {
        "PYTHONUTF8": "1",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Para añadir las credenciales HANA directamente aquí (opción recomendada):

"env": {
  "PYTHONUTF8": "1",
  "PYTHONIOENCODING": "utf-8",
  "HANA_HOST": "tu-instancia.hanacloud.ondemand.com",
  "HANA_PORT": "443",
  "HANA_USER": "DBADMIN",
  "HANA_PASSWORD": "tu_password",
  "HANA_SCHEMA": ""
}

Las 28 tools MCP disponibles

Filesystem + Config (11 tools)

Terminal (2 tools)

Gestión de procesos psutil (2 tools)

Sesiones interactivas (5 tools) ⭐

Flujo ejemplo — REPL Python interactivo:

start_process("python -i")
  → [PID 4521] Process started (running)

interact_with_process(4521, "import pyswisseph as swe")
interact_with_process(4521, "print(swe.calc_ut(2460000, 0))")
  → ((189.43, 1.0, 0.0, ...), 0)

interact_with_process(4521, "exit()")

SAP HANA Cloud — hdbcli (8 tools) 🔷

Configurar credenciales SAP HANA Cloud

Las credenciales nunca se hardcodean en código y config/hana_config.yaml está en .gitignore para que nunca lleguen a GitHub.

Opción A — Variables de entorno en claude_desktop_config.json (recomendada)

Ventajas: no hay fichero de credenciales en disco, fácil de cambiar por entorno.

"env": {
  "HANA_HOST": "xxxxxxxx-xxxx.hana.trial-us10.hanacloud.ondemand.com",
  "HANA_PORT": "443",
  "HANA_USER": "DBADMIN",
  "HANA_PASSWORD": "tu_password_aqui",
  "HANA_SCHEMA": ""
}

Opción B — Fichero local config/hana_config.yaml

hana:
  host: "xxxxxxxx-xxxx.hana.trial-us10.hanacloud.ondemand.com"
  port: 443
  user: "DBADMIN"
  password: "tu_password_aqui"
  schema: ""
  encrypt: true
  sslValidateCertificate: true
  max_rows: 200

Copiar la plantilla y rellenar:

copy config\hana_config.yaml.example config\hana_config.yaml
# editar hana_config.yaml con datos reales

Cómo obtener el host en BTP Free Tier

1. Entra en BTP Cockpit

2. Selecciona tu subaccount → Instances and Subscriptions

3. Busca tu instancia SAP HANA Cloud

4. Haz clic en los tres puntos → Open in SAP HANA Database Explorer

5. El host está en la barra de conexión: xxxxxxxx-xxxx.hana.trial-us10.hanacloud.ondemand.com (el puerto siempre es 443 en HANA Cloud)

Verificar la conexión tras configurar

Reinicia Claude Desktop y ejecuta:

hana_test_connection()

Respuesta esperada:

✓ Conexión exitosa a SAP HANA Cloud
  Host:           tu-instancia.hanacloud.ondemand.com:443
  Usuario:        DBADMIN
  Schema actual:  DBADMIN
  Versión HANA:   4.00.000.00.1234567890
  Conexiones propias activas: 1
  SSL/TLS:        activado

Flujo típico de exploración

hana_test_connection()                           → verifica credenciales
hana_get_system_info()                           → estado del Free Tier
hana_list_schemas()                              → schemas disponibles
hana_list_tables("DBADMIN")                      → tablas del schema
hana_describe_table("MI_TABLA", "DBADMIN")       → estructura de la tabla
hana_get_row_count("ORDERS,ITEMS,CUSTOMERS")     → filas sin full scan
hana_execute_query("SELECT TOP 10 * FROM ORDERS") → datos
hana_execute_ddl("CREATE TABLE TEST (ID INT)", confirm=True)

Límites del Free Tier a tener en cuenta

• Memoria: 30 GB RAM total (monitorizeable con hana_get_system_info)

• Almacenamiento: 120 GB disco

• Conexiones simultáneas: limitadas — hana_get_system_info muestra el contador

• La instancia se para sola si no hay actividad en un período — hana_test_connection te dirá si está caída con un error de conexión claro

Tests

.venv\Scripts\pytest.exe tests/ -v

Salida esperada: 32 passed in ~2-3s

Guía operacional — patrones y limitaciones conocidas

Sección de referencia rápida para uso desde Claude Desktop.

P1 — execute_command no encuentra python, python3 ni cmd

Síntoma: python: command not found o similar al ejecutar comandos Python.

Causa: Claude Desktop arranca con un PATH minimal de escritorio, no el PATH completo de la sesión de usuario. execute_command hereda ese PATH restringido.

Solución A (fix permanente, ya integrado): build_subprocess_env() en utils.py enriquece automáticamente el PATH del subprocess con los directorios del venv activo, el Python base y el launcher py.exe. Desde la versión actual esto es transparente.

Solución B (si A falla): usar Desktop Commander:start_process con py explícito:

Desktop Commander:start_process { command: "py script.py", timeout_ms: 25000 }

P2 — C:/temp/ bloqueado para escritura

Causa: security_config.yaml tiene una lista explícita de allowed_directories. C:\temp no está en ella, no es un bug.

Directorios permitidos en este sistema:

• C:/Users/Edu/Documents (y subdirectorios, incluido ClaudeWork)

• C:/Users/Edu/Desktop

• C:/Users/Edu/Downloads

• C:/Users/Edu/DesktopCommanderPy

• C:/Users/Edu/VerbaSant

• C:/Users/Edu/AstroExtracto

• C:/Users/Edu/AstroCompendium

• C:/Users/Edu/MetaAstrum

• C:/Users/Edu/VTTs

• C:/Users/Edu/astro_cartas

Destino por defecto recomendado: C:/Users/Edu/Documents/

P2b — Paths relativos, ~ y Windows mezclan mal separadores

Estado actual: resuelto en la capa runtime nueva.

Ahora todas las tools principales pasan por un helper común que:

• expande ~

• resuelve rutas relativas contra el cwd

• normaliza separadores y casing en Windows

• usa resolve(strict=False) antes de validar sandbox

Eso evita muchos falsos negativos típicos de Windows cuando una ruta entra como: ~/algo.txt, .\archivo.py, C:/Users/Edu/... o C:\Users\Edu\...

Implementación: core/tools/utils.py → resolve_and_validate_path()

P2c — Config stringly-typed: true/false, números y arrays acababan mal

Estado actual: resuelto con configuración runtime central.

Antes, cada módulo podía releer YAML y varias flags acababan tratándose como texto. Ahora existe una única fuente de verdad:

• core/runtime_config.py

• core/tools/config_tools.py

Y se exponen dos tools MCP nuevas:

get_config()
set_config_value(key, value)

Los tipos se preservan como tipos Python reales:

• bool

• int

• str

• list[str]

Esto hace el servidor mucho más predecible y evita bugs por valores tipo "false" o "45" tratados como strings.

P3 — Desktop Commander:write_file (Node.js) bloquea la palabra dd

Causa: El servidor Node.js Desktop Commander tiene su propio blacklist de comandos de shell. La cadena dd coincide como substring, bloqueando cualquier fichero cuyo contenido incluya esa secuencia (nombres de variable, paths, texto).

Solución: usar DesktopCommanderPy:write_file para escribir ficheros con contenido arbitrario — no tiene ese filtro. Reservar Desktop Commander:write_file solo si DesktopCommanderPy no responde por permisos de path.

P4 — Encoding: UnicodeEncodeError con caracteres especiales en Windows

Causa: La consola de Windows usa cp1252 por defecto. Caracteres como ≤, °, → causan UnicodeEncodeError si el script no fuerza UTF-8.

Solución A (preferida, ya integrada): build_subprocess_env() fija PYTHONUTF8=1 y PYTHONIOENCODING=utf-8 en todos los subprocesos.

Solución B: lanzar con py -X utf8 script.py.

Solución C: añadir al inicio del script:

import sys, io
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')

Solución D (fallback): evitar caracteres especiales en el output: usar d en vez de °, <= en vez de ≤, -> en vez de →.

P5 — REPL interactivo frágil: no pegar funciones multilínea

Síntoma: errores de indentación o sintaxis al enviar bloques de código al REPL (py -i + interact_with_process).

Causa: el protocolo de sesiones interactivas no maneja bien los bloques multilínea — el REPL ve las líneas de forma fragmentada.

Solución: siempre escribir el script completo a fichero y ejecutarlo de una sola vez. Nunca intentar pegar funciones o clases enteras en el REPL.

Patrón correcto:

DesktopCommanderPy:write_file  → C:/Users/Edu/Documents/script.py
Desktop Commander:start_process → py -X utf8 C:/Users/Edu/Documents/script.py

P6 — present_files solo funciona con rutas /mnt/... del contenedor Claude

Causa: present_files genera enlaces de descarga solo para el filesystem interno del contenedor Claude (/mnt/user-data/outputs/). No puede crear enlaces para C:\Users\Edu\....

Solución: indicar al usuario la ruta local donde está guardado el fichero. No hay workaround disponible desde el servidor MCP.

🐛 Bugs críticos resueltos — diario de guerra

Bug 1 — spawn uv ENOENT: Claude Desktop no arrancaba

Período: 8 de marzo al 26 de marzo de 2026.

Síntomas:

• %APPDATA%\Claude\logs\mcp-server-*.log → spawn uv ENOENT en bucle

• main1.log → Request timed out: isGuestConnected repetido cada pocos segundos

• Claude Desktop colgado en la pantalla de carga

• Más de 10 procesos de Claude bloqueados en segundo plano (detectados por Gemini CLI)

Causa raíz: El MCP oficial Desktop Commander usa uv para gestionar su entorno Python. uv no estaba instalado o no estaba en el PATH que hereda Claude Desktop al arrancar como aplicación de escritorio — que es diferente al PATH de la terminal.

Solución:

# 1. Instalar uv (script oficial Astral)
# → binario en C:\Users\Edu\.local\bin\uv.exe

# 2. Añadir al PATH de usuario del SISTEMA (no solo de la sesión)
[System.Environment]::SetEnvironmentVariable(
    "PATH",
    "C:\Users\Edu\.local\bin;" + [System.Environment]::GetEnvironmentVariable("PATH","User"),
    "User"
)

# 3. Verificar
[System.Environment]::GetEnvironmentVariable("PATH","User")
# debe empezar por: C:\Users\Edu\.local\bin;...

# 4. Reiniciar Claude Desktop

Verificación:

C:\Users\Edu\.local\bin\uv.exe --version
# uv 0.11.1

Bug 2 — Banner ASCII de FastMCP: Claude Desktop se colgaba al conectar

Síntomas:

• Claude Desktop arrancaba pero nunca terminaba de inicializar el MCP propio

• El servidor arrancaba (visible en logs) pero Claude nunca recibía respuesta de initialize

• Detectado y diagnosticado por Gemini CLI analizando los logs

Causa raíz: FastMCP imprime por defecto un banner ASCII decorativo por stdout al arrancar. Claude Desktop usa JSON-RPC estricto sobre stdout: cualquier byte no-JSON rompe el protocolo y deja a Claude esperando indefinidamente sin mensaje de error.

╭────────────────────────────╮
│   FastMCP Server v3.x      │   ← esto va a stdout y destruye el canal JSON-RPC
╰────────────────────────────╯

La regla fundamental del transporte stdio MCP:

stdout es un canal binario exclusivo para JSON-RPC. Absolutamente nada más puede escribirse en él. Logs, banners y mensajes van a stderr.

Solución:

# main.py — CRÍTICO: nunca eliminar este flag
mcp.run(transport="stdio", show_banner=False)

Test de regresión: TestStdioTransport::test_server_stdout_is_clean_on_startup lanza el proceso real y verifica que el primer byte de stdout sea {. Si una actualización futura de FastMCP cambia el comportamiento, el test falla antes de llegar a Claude Desktop.

Bug 3 — Deadlock stdin: Python/pytest devolvían output vacío

Síntomas:

• Get-Date, where.exe, dir → funcionaban perfectamente

• Cualquier proceso Python (incluido pytest) → output vacío, timeout o cuelgue total

• El proceso Python aparecía en el gestor de tareas corriendo pero sin terminar

Causa raíz: Al lanzar subprocesos sin especificar stdin, el hijo hereda el stdin del padre — que en este caso es el canal JSON-RPC de Claude Desktop. Python y otros intérpretes leen stdin al arrancar para detectar modo interactivo. Al hacerlo, bloquean esperando input que nunca llega → deadlock en cascada:

Claude Desktop → [JSON-RPC stdin] → Servidor MCP
                                         ↓
                                    asyncio.create_subprocess_exec
                                         ↓ (sin stdin=DEVNULL)
                                    Python hijo hereda stdin MCP
                                         ↓
                                    Python lee stdin → BLOQUEO ETERNO
                                         ↓
                                    Servidor MCP espera al hijo → BLOQUEO
                                         ↓
                                    Claude Desktop espera al servidor → BLOQUEO

Solución:

proc = await asyncio.create_subprocess_exec(
    *shell_args, command,
    stdin=asyncio.subprocess.DEVNULL,   # ← el hijo ve /dev/null, no el canal MCP
    stdout=asyncio.subprocess.PIPE,
    stderr=asyncio.subprocess.STDOUT,
    cwd=cwd,
    env=env,
)

Aplicado en execute_command y execute_command_streaming.

Nota: Las sesiones interactivas (start_process) usan stdin=PIPE deliberadamente — es lo que permite enviarles input con interact_with_process. La diferencia es que ahí el stdin lo gestiona el servidor, no lo hereda del canal MCP.

Arquitectura — Gestor de sesiones

session_manager.py implementa un SessionManager singleton con un dict {pid: ProcessSession} por proceso activo.

Cada ProcessSession contiene:

• El objeto asyncio.subprocess.Process

• Un asyncio.Queue donde se acumula todo el output

• Un asyncio.Task que drena stdout en background línea a línea

• Metadatos: comando, timestamp de inicio, líneas emitidas, estado

start_process("python -i")
    ├── create_subprocess_exec(stdin=PIPE, stdout=PIPE)
    ├── ProcessSession(pid, queue=Queue())
    ├── asyncio.create_task(drain_output(session))   ← background forever
    └── sessions.register(session)

drain_output [Task en background]:
    async for line in process.stdout:
        await queue.put(line)
    await queue.put(None)   ← señal de fin de stream

interact_with_process(pid, "print('hola')"):
    ├── process.stdin.write(b"print('hola')\n")
    ├── await process.stdin.drain()
    └── read_output(session, timeout=8s)
            └── asyncio.wait_for(queue.get(), 0.5s) × N iteraciones

Historial de commits

Bug 4 — Matching de substring en blacklist: dd bloqueaba address, adding, hidden…

Detectado: 28 de marzo de 2026.

Síntomas:

• Desktop Commander:write_file (Node.js) bloqueaba ficheros con contenido normal que contenía la cadena dd (variables, paths, palabras)

• Pero también el propio check_command_allowed de DesktopCommanderPy afectado: comandos legítimos como black --reformat . eran bloqueados si contenían subcadenas coincidentes con tokens de la blacklist

Causa raíz: El matching era blocked.lower() in cmd_lower — búsqueda de substring pura. El token "dd" en blocked_commands coincidía en cualquier posición:

# Antes del fix — INCORRECTO
"dd" in "address"   # True → bloqueaba 'address'
"dd" in "adding"    # True → bloqueaba 'adding'
"format" in "reformat"  # True → bloqueaba '--reformat'

Solución:

# Después del fix — word-boundary regex
pattern = r"\b" + re.escape(blocked.lower()) + r"\b"
re.search(pattern, "address")   # None → permitido ✓
re.search(pattern, "dd if=...")  # Match → bloqueado ✓
re.search(r"\bformat\b", "--reformat")  # None → permitido ✓
re.search(r"\bformat\b", "format C:")   # Match → bloqueado ✓

Los patrones multi-palabra como "net user" siguen funcionando exactamente igual.

Bug 5 — PATH minimal: subprocesos no encontraban python, python3, pip

Detectado: 28 de marzo de 2026.

Síntomas:

• execute_command("python script.py") → python: command not found

• execute_command("pip install X") → error similar

• Get-Date, dir, where.exe → funcionaban sin problema

Causa raíz: Claude Desktop se lanza como aplicación de escritorio de Windows, no desde una terminal de usuario. El PATH que hereda es el PATH del sistema, sin las entradas que el instalador de Python añade al PATH del usuario:

PATH de terminal usuario:  C:\Users\Edu\AppData\Local\Programs\Python\Python312\Scripts;...
PATH heredado por Claude:  C:\Windows\System32;C:\Windows;...  (sin Python)

Solución — build_subprocess_env() en utils.py:

def build_subprocess_env(extra=None):
    env = os.environ.copy()
    env["PYTHONUTF8"] = "1"
    env["PYTHONIOENCODING"] = "utf-8"
    # Prepend: venv Scripts, base Python Scripts, C:\Windows (py.exe), LOCALAPPDATA Python
    ...
    return env

Aplicado en execute_command y execute_command_streaming. Los subprocesos ahora reciben el PATH completo independientemente de cómo arrancó Claude Desktop.

Roadmap| Feature | Prioridad |

|---------|-----------| | Tests para módulo HANA (mock de hdbcli) | 🔴 Alta | | get_config / set_config_value en runtime | 🟡 Media | | Audit log con rotación | 🟡 Media | | copy_file | 🟡 Media | | start_search asíncrono con paginación | 🟡 Media | | Restricciones allowed_dirs por tool | 🟢 Baja | | Modo multi-IA: HTTP + auth token | 🟢 Baja | | Tools astrología (pyswisseph, VTTs) | 🟢 Baja | | Tools SAP adicionales (pyrfc, RFC ping) | 🟢 Baja |

Licencia

MIT — haz lo que quieras, conserva la nota de copyright.