MCP en el homelab. Conecta Claude Code con tu infraestructura
Llevas años automatizando tu infraestructura con scripts, Ansible y cron. Funciona. Pero cada vez que quieres que algo haga algo tienes que decirle exactamente cómo hacerlo. Con MCP, Claude Code puede hacer el trabajo directamente — sin que tú escribas ni un comando.
Este artículo es el primero de una serie de cinco. Aquí explico qué es MCP y cómo está organizado el proyecto. Los siguientes entran en detalle en cada uno de los cuatro servidores.
🔌 Qué es MCP
MCP (Model Context Protocol) es el protocolo que define cómo un LLM se comunica con herramientas externas. Lo publicó Anthropic en 2024 y lo usa Claude Code para todo lo que va más allá del chat: leer ficheros, ejecutar comandos, buscar en bases de datos.
Sin MCP, Claude Code ve solo lo que está en el contexto de la conversación. Con MCP, puede actuar sobre sistemas reales: ejecutar un comando SSH, leer una nota de Obsidian, lanzar un escaneo de red.
Cada servidor MCP expone un conjunto de herramientas (funciones que el LLM puede llamar). Claude decide cuándo usarlas y con qué argumentos, igual que tú decides qué comando ejecutar.
🗂️ El proyecto harper-mcps
harper-mcps es una colección de cuatro servidores MCP diseñados para un homelab autogestionado. Cada servidor cubre un dominio distinto:
| Servidor | Herramientas | Para qué |
|---|---|---|
mcp_obsidian_server.py | search, read, write, list, tags, backlinks | Gestionar un vault de Obsidian |
mcp_ssh_server.py | ssh_run, ssh_read/write, ssh_check, nmap_* | Ejecutar comandos en hosts remotos y escanear red |
mcp_winrm_server.py | winrm_run_ps, winrm_read/write, winrm_install | Administrar máquinas Windows |
mcp_osint_server.py | username, email, domain, whois, dns, ip, dossier | Investigación OSINT |
Los cuatro son independientes: puedes usar solo el que necesites.
⚡ Por qué stdio y sin FastMCP
Todos los servidores usan transporte stdio (entrada/salida estándar) y están escritos sobre la librería mcp sin FastMCP. La razón es simple: FastMCP añade capas de abstracción que ralentizan el arranque. Con stdio puro, cada servidor arranca en menos de 20ms. Claude Code lanza y cierra servidores MCP en cada sesión — esos milisegundos se notan.
🚀 Instalación
git clone https://github.com/jaimealberto/harper-mcps.git
cd harper-mcps
# Dependencias según los servidores que vayas a usar:
pip install mcp # Obsidian
pip install pywinrm urllib3 # WinRM
pip install python-whois dnspython phonenumbers # OSINT base
# SSH no necesita nada en Python — usa el ssh del sistema⚙️ Configuración en Claude Code
Los servidores MCP se declaran en ~/.claude.json bajo la clave mcpServers. Un ejemplo con los cuatro activos:
{
"mcpServers": {
"harper-obsidian": {
"type": "stdio",
"command": "python3",
"args": ["/ruta/a/harper-mcps/mcp_obsidian_server.py"],
"env": { "OBSIDIAN_VAULT": "/home/usuario/Obsidian" }
},
"harper-ssh": {
"type": "stdio",
"command": "python3",
"args": ["/ruta/a/harper-mcps/mcp_ssh_server.py"],
"env": {}
},
"harper-winrm": {
"type": "stdio",
"command": "python3",
"args": ["/ruta/a/harper-mcps/mcp_winrm_server.py"],
"env": {}
},
"harper-osint": {
"type": "stdio",
"command": "python3",
"args": ["/ruta/a/harper-mcps/mcp_osint_server.py"],
"env": {}
}
}
}También puedes añadirlos con claude mcp add desde la terminal. Consulta el claude_settings_example.json del repo para la configuración completa lista para copiar.
📚 La serie
- [Parte 1 — Introducción] ← estás aquí
- Parte 2 — harper-obsidian: tu vault desde el chat
- Parte 3 — harper-ssh: SSH y nmap sin salir de Claude
- Parte 4 — harper-winrm: administrar Windows desde Linux
- Parte 5 — harper-osint: investigación de fuentes abiertas
