Si llevas semanas leyendo sobre Model Context Protocol sin atreverte a instalar tu primer servidor, esta guía es para ti. En 15 minutos vas a tener Claude Desktop conectado a un servidor MCP real, ejecutando acciones sobre tu sistema de archivos o sobre una API externa, y entendiendo qué hace cada pieza.
Qué necesitas antes de empezar
Tres cosas. Primero, Claude Desktop instalado en macOS, Windows o Linux (la versión 0.7+ es la mínima recomendada). Segundo, un runtime: Node.js 18+ si vas a usar servidores escritos en TypeScript (la mayoría), o uv de Astral si vas a usar servidores en Python. Tercero, un editor de texto plano para tocar el archivo de configuración.
No necesitas Docker, ni una API key de Anthropic adicional, ni cuenta de pago. Los servidores MCP corren localmente en tu máquina y se comunican con Claude Desktop por stdio (entrada y salida estándar). El modelo no envía tu código fuente a Anthropic: solo el resultado de las herramientas que tú apruebes.
Paso 1: encontrar el archivo de configuración
Claude Desktop guarda la lista de servidores MCP en un único JSON. La ubicación cambia por sistema operativo:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%Claudeclaude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Si el archivo no existe, créalo con contenido inicial {"mcpServers": {}}. Si Claude Desktop nunca lo ha generado, abre la app, ve a Settings → Developer → Edit Config, y la app lo creará por ti.
Paso 2: elegir un servidor de prueba
Para una primera instalación recomiendo filesystem-mcp (oficial, sin API keys, lectura/escritura de archivos en una carpeta que tú elijas). Es el “hola mundo” del ecosistema y te permite verificar que la conexión funciona sin pagar nada ni configurar OAuth.
Si prefieres algo más vistoso, prueba memory-mcp (memoria persistente entre conversaciones) o time-mcp (zonas horarias). Encontrarás todos en el directorio de servidores MCP en español, con descripción, comando de instalación y casos de uso.
Paso 3: editar claude_desktop_config.json
Para filesystem-mcp el bloque queda así (ajusta la ruta a una carpeta que quieras dar acceso):
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/tu-usuario/Documentos/mcp-test"]
}
}
}Guarda el archivo. Cierra Claude Desktop completamente (no solo la ventana — desde Cmd+Q en macOS, desde el ícono de tray en Windows). Vuelve a abrirlo.
Paso 4: verificar que el servidor cargó
En la barra de chat de Claude Desktop debería aparecer un ícono de martillo (🔨) abajo a la derecha. Al hacer clic, ves la lista de herramientas que el servidor expone: read_file, write_file, list_directory, etc. Si no aparece nada, hay un error de conexión.
Para depurar, abre el log: ~/Library/Logs/Claude/mcp.log en macOS o el equivalente en tu OS. Errores frecuentes: ruta inválida en args, Node.js no instalado en el PATH, o JSON mal formado (una coma de más rompe todo el archivo).
Paso 5: probar el servidor con un prompt real
Pídele a Claude algo como: “Lista los archivos de mi carpeta de pruebas y dime cuáles son markdown”. Verás que te pide aprobación antes de ejecutar la herramienta — siempre tendrás que confirmar la primera vez. Aprueba y observa el resultado real, no una alucinación.
Errores comunes y cómo resolverlos
- “npx: command not found”: Node.js no está instalado o no está en el PATH del proceso de Claude. En macOS instálalo con
brew install node; en Windows desde nodejs.org. - “Server disconnected”: el servidor crashea al arrancar. Ejecuta el comando manualmente en una terminal para ver el stack trace real.
- “No tools available”: el JSON está bien formado pero el servidor no expone tools. Revisa que estés usando el paquete oficial.
- El ícono no aparece: versión vieja de Claude Desktop. Actualiza desde claude.ai/download.
Siguiente paso
Una vez tengas filesystem funcionando, prueba un servidor con API key real (PostgreSQL, Slack, GitHub) — la lógica es idéntica, solo añades la variable de entorno en el bloque "env". Y si ya estás en flujo de desarrollo, considera la integración con Cursor: el formato del config es muy similar pero con detalles propios.