Tutorial MCP servers en Claude Code: guía de instalación paso a paso (agosto 2026)

Los servidores MCP (Model Context Protocol) han pasado de curiosidad técnica a pieza central del flujo de trabajo de cualquier desarrollador que use Claude Code a diario. En este tutorial paso a paso te enseño a instalar y configurar cinco servidores MCP imprescindibles (filesystem, GitHub, SQLite, Puppeteer y uno personalizado en Python) sobre Claude Code 2.x, con los cambios que Anthropic introdujo en la versión de agosto de 2026. Todos los ejemplos están probados en Linux y macOS; los apartados específicos de Windows se marcan aparte.

Este tutorial asume que ya has usado Claude Code alguna vez, que tienes cuenta activa en Anthropic y que trabajas con Node.js y Python instalados. Si vienes de cero, empieza por el paso 1 de todos modos: hay cambios recientes en la CLI que conviene conocer.

Qué es MCP y por qué te interesa

El Model Context Protocol es un estándar abierto publicado por Anthropic a finales de 2024 que define cómo un modelo de lenguaje (Claude, en nuestro caso) se comunica con herramientas externas mediante un contrato JSON-RPC sobre stdio o HTTP. La gracia es que el mismo servidor MCP funciona en Claude Code, Claude Desktop, Cursor, Cline, Continue y cualquier cliente compatible: escribes una integración una vez y la reutilizas en todos lados.

Para el usuario final la diferencia es enorme. Sin MCP, cada vez que quieres que Claude lea un archivo tienes que pegarlo en la conversación. Con MCP configurado, Claude Code decide cuándo llamar a la herramienta read_file o list_directory, ejecuta la operación en tu equipo y trae el resultado como contexto. La conversación se centra en el objetivo, no en el copia-pega.

Si quieres profundizar en el ecosistema Anthropic, revisa nuestro tutorial anterior sobre cómo instalar Claude Code y configurarlo desde cero. Aquí damos por hecho ese paso y vamos directo a los MCP.

Como se comunican Claude Code y los servidores MCP

La comunicacion es siempre JSON-RPC 2.0. Claude Code inicia el proceso del servidor (transporte stdio) o abre una conexion HTTP contra un endpoint (transporte HTTP con SSE). Envia un handshake initialize, recibe la lista de capacidades (tools, resources, prompts) y a partir de ahi las llamadas se hacen por nombre. Cuando el modelo decide usar una herramienta, Claude Code manda un tools/call con los argumentos, el servidor responde con el resultado y Claude reincorpora ese resultado al contexto. Todo esto es transparente para el usuario, pero conocer el flujo ayuda muchisimo cuando algo falla y hay que meter tcpdump o mirar logs a bajo nivel.

La otra pieza que conviene tener clara son los tres tipos de capacidad que un servidor puede exponer: tools (funciones que Claude invoca activamente), resources (contenido leible por URI, como si fueran archivos virtuales) y prompts (plantillas reutilizables que aparecen en el selector de Claude Code al pulsar /). En la practica la mayoria de servidores exponen tools; resources y prompts estan mas infrautilizados pero son los que dan versatilidad al ecosistema.

Prerequisitos: qué necesitas antes de empezar

Antes de tocar nada, revisa esta lista. Ahorra media hora de dolor.

• Claude Code 2.4 o superior. La versión de agosto de 2026 renombró varios comandos y añadió claude mcp como namespace unificado. Comprueba con claude --version.
• Node.js 20 LTS o 22 LTS. Muchos servidores MCP oficiales se distribuyen como paquetes npm ejecutables con npx.
• Python 3.11 o superior. Necesario para el servidor personalizado y para uv, el gestor rápido de dependencias que recomienda Anthropic.
• uv instalado. Lo usaremos como runner de servidores Python: curl -LsSf https://astral.sh/uv/install.sh | sh en Linux y macOS.
• Un token clásico de GitHub con scopes repo y read:org. Los fine-grained tokens también funcionan desde julio, pero requieren configurar permisos por repositorio.
• Chromium o Chrome instalado si vas a usar Puppeteer. En servidores headless, apt install chromium.

Un consejo antes de continuar: crea un directorio ~/proyectos/mcp-lab vacío y trabaja ahí. Los servidores MCP tocan tu filesystem con permisos amplios y no quieres probar cosas nuevas sobre el repositorio de tu empresa.

Paso 1: instalar y actualizar Claude Code

Si ya tienes Claude Code, salta al comando de actualización. Si no, la instalación oficial es un one-liner:

curl -fsSL https://claude.ai/install.sh | bash

Esto instala el binario en ~/.local/bin/claude y añade la ruta al PATH. Cierra y vuelve a abrir la terminal, o ejecuta source ~/.bashrc. Verifica con:

claude --version
# claude 2.4.1 (2026-08-05)
claude doctor

El comando claude doctor es nuevo desde julio: comprueba versión de Node, permisos, conexión con Anthropic y credenciales OAuth. Si algún check falla, arregla eso antes de seguir. Actualizar es igual de simple:

claude update

Una vez dentro, autentícate con claude login. Se abrirá el navegador con el flujo OAuth. Para uso corporativo, tienes también claude login --api-key pasando la key de la consola de Anthropic.

Paso 2: configurar el servidor MCP filesystem

Filesystem es el MCP más útil desde el minuto uno. Da a Claude Code herramientas para leer, listar, escribir y buscar archivos dentro de los directorios que tú decidas. Se instala con un solo comando:

claude mcp add filesystem \
  --scope user \
  --transport stdio \
  -- npx -y @modelcontextprotocol/server-filesystem \
  ~/proyectos/mcp-lab

Desglosemos:

• filesystem: nombre local del servidor. Aparece luego en claude mcp list.
• --scope user: se registra en ~/.config/claude/mcp.json (global). Alternativas: --scope project (guarda en .claude/mcp.json del directorio actual) y --scope local (temporal para la sesión).
• --transport stdio: la conexión va por entrada y salida estándar del proceso. Es el modo por defecto y el más rápido.
• Después del -- viene el comando que Claude Code ejecutará para levantar el servidor.
• El último argumento es el directorio raíz que el servidor puede tocar. Puedes pasar varios separados por espacios.

Verifica con claude mcp list. Deberías ver filesystem (stdio, conectado). Ahora abre Claude Code (claude) y prueba:

Lista los archivos .md del directorio raíz que tienes configurado.

Claude debería invocar la herramienta list_directory y devolverte los archivos. Si en lugar de eso te pide que se los pegues, revisa que el servidor esté conectado y que hayas reiniciado Claude Code tras el registro.

Buenas prácticas de seguridad con filesystem

Este servidor tiene permisos amplios: si le das ~/, Claude puede leer y modificar cualquier cosa bajo tu home. Nunca lo hagas. Registra siempre directorios acotados y usa el flag --read-only del servidor si solo quieres consulta:

claude mcp add filesystem-lectura \
  --scope user \
  -- npx -y @modelcontextprotocol/server-filesystem \
  --read-only ~/documentos/notas

Paso 3: añadir el servidor MCP de GitHub

El servidor oficial de GitHub aporta un catálogo grande: list_pull_requests, create_issue, get_file_contents, merge_pull_request, search_code y unas cuantas decenas más. Necesitas un token clásico o fine-grained con los scopes que mencionábamos en los prerequisitos.

Exporta el token como variable de entorno para no dejarlo en el JSON:

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_XXXXXXXXXXXXXXXXXXXX"

Y registra el servidor:

claude mcp add github \
  --scope user \
  --env GITHUB_PERSONAL_ACCESS_TOKEN \
  -- npx -y @modelcontextprotocol/server-github

El flag --env le dice a Claude Code que reenvíe esa variable al proceso del servidor. Nunca pegues el token directamente en el comando: aparecería en el historial y en el archivo mcp.json.

Prueba con:

Lista los pull requests abiertos del repositorio anthropics/claude-code.

Claude Code hará una petición autenticada y te devolverá los PRs. Si vas a trabajar con repos privados, asegúrate de que el token tenga acceso a la organización correspondiente.

Restringir a repositorios concretos

Por defecto el servidor puede tocar cualquier repo al que llegue el token. Desde la versión 0.6 puedes limitar con la variable GITHUB_ALLOWED_REPOS:

export GITHUB_ALLOWED_REPOS="miorg/repo-a,miorg/repo-b"

Y reconstruye el registro con claude mcp remove github seguido de un add nuevo pasando también --env GITHUB_ALLOWED_REPOS.

Paso 4: SQLite MCP para consultar bases de datos locales

Aquí empieza la parte divertida: dejar que Claude explore una base de datos SQLite real y te ayude a escribir queries, hacer análisis exploratorio o migrar esquemas. Anthropic mantiene un servidor oficial en Python que se ejecuta con uvx (el runner one-shot de uv).

Primero, ten a mano un archivo .sqlite o .db. Si no tienes ninguno, crea uno de juguete:

sqlite3 ~/proyectos/mcp-lab/ventas.db <<'SQL'
CREATE TABLE ventas (id INTEGER, producto TEXT, cantidad INT, fecha DATE);
INSERT INTO ventas VALUES
 (1, 'teclado mecanico', 3, '2026-07-15'),
 (2, 'monitor 4k',       1, '2026-07-16'),
 (3, 'silla ergonomica', 2, '2026-08-01');
SQL

Registra el servidor:

claude mcp add sqlite \
  --scope project \
  -- uvx mcp-server-sqlite --db-path ~/proyectos/mcp-lab/ventas.db

Al usar --scope project, la configuración se guarda en .claude/mcp.json del directorio actual, lo cual es lo correcto para servidores atados a un proyecto concreto. Prueba en Claude Code:

Muestra el esquema de la tabla ventas y calcula cuantos productos se vendieron en agosto de 2026.

Claude debería invocar list_tables, describe_table y read_query para responderte con una tabla resumen. La primera vez pedirá permiso interactivo para ejecutar la query; puedes concederlo permanentemente si trabajas en un entorno de desarrollo.

Modo lectura vs modo escritura

Por defecto, mcp-server-sqlite permite write_query (INSERT, UPDATE, DELETE) y create_table. Si estás explorando una base productiva, arranca con --read-only para bloquear cualquier modificación. Nunca conectes un SQLite productivo sin backup previo.

Paso 5: Puppeteer MCP para navegar y hacer scraping web

El servidor @modelcontextprotocol/server-puppeteer lanza una instancia de Chromium controlada por Claude Code. Con el, la IA puede abrir URLs, hacer clicks, rellenar formularios, tomar screenshots y extraer HTML renderizado (incluidos sitios con mucho JavaScript). Es la manera correcta de que Claude lea una web moderna en 2026 en vez de un simple fetch.

claude mcp add puppeteer \
  --scope user \
  --env PUPPETEER_HEADLESS=true \
  -- npx -y @modelcontextprotocol/server-puppeteer

La primera invocacion descarga Chromium (~180 MB) si no lo tienes. En Linux servidor manda instalar dependencias con apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libx11-xcb1 libxcomposite1 libxrandr2 libgbm1 libpangocairo-1.0-0 libasound2.

Prueba con algo inocuo:

Navega a https://arkaiacorp.com/blog, toma una captura, y dime cuantos articulos ves en la portada.

Claude llamara a puppeteer_navigate, puppeteer_screenshot y puppeteer_evaluate para inspeccionar el DOM.

Aviso de rate limiting y buenas maneras

Puppeteer da a Claude el poder de martillear cualquier web. Respeta los robots.txt, no scrapees sitios de pago y usa PUPPETEER_ARGS="--disable-blink-features=AutomationControlled" con moderacion. Un servidor MCP no te libera de las mismas responsabilidades que tendrias con un scraper propio.

Paso 6: crear tu propio servidor MCP en Python

Los servidores oficiales cubren mucho, pero antes o despues necesitas exponer una API interna, una base de datos exotica o una integracion con un SaaS que no tiene servidor todavia. Escribir uno propio en Python son 40 lineas.

Crea el directorio y el entorno:

mkdir -p ~/proyectos/mcp-lab/mi-mcp && cd $_
uv init --package mi-mcp
uv add mcp

Edita src/mi_mcp/__init__.py:

from mcp.server.fastmcp import FastMCP
import datetime

mcp = FastMCP("mi-mcp")

@mcp.tool()
def saludar(nombre: str) -> str:
    """Devuelve un saludo personalizado con la hora actual."""
    ahora = datetime.datetime.now().strftime("%H:%M")
    return f"Hola {nombre}, son las {ahora}. Que tengas buen dia."

@mcp.tool()
def contar_palabras(texto: str) -> int:
    """Cuenta palabras en un texto."""
    return len(texto.split())

def main() -> None:
    mcp.run(transport="stdio")

Registralo en Claude Code apuntando a uv run:

claude mcp add mi-mcp \
  --scope project \
  -- uv --directory ~/proyectos/mcp-lab/mi-mcp run mi-mcp

Reinicia Claude Code y pide:

Usa la herramienta saludar con mi nombre y luego cuenta las palabras de esta frase.

La libreria FastMCP deduce el schema de los parametros a partir de los type hints y las docstrings, asi que tu solo escribes funciones Python normales. Puedes anadir @mcp.resource para exponer archivos o URIs, y @mcp.prompt para plantillas reutilizables. La documentacion oficial esta en el repositorio modelcontextprotocol/python-sdk en GitHub.

Exponer un recurso y un prompt reutilizable

Amplia el archivo con dos capacidades mas: un recurso que devuelva el contenido de un archivo de configuracion y un prompt que prepare a Claude para revisar un pull request:

from pathlib import Path

@mcp.resource("config://actual")
def leer_config() -> str:
    """Devuelve el contenido de config.yaml del proyecto."""
    return Path("~/proyectos/mcp-lab/config.yaml").expanduser().read_text()

@mcp.prompt("revisar-pr")
def revisar_pr(numero: int) -> str:
    """Prompt reutilizable para revisar un pull request por su numero."""
    return (
        f"Revisa el PR #{numero} del repositorio actual. Comprueba "
        "tests, cobertura, side effects y guia de estilo del equipo. "
        "Al terminar, resume en tres bullets y propon aprobacion o cambios."
    )

Tras recargar Claude Code, veras el prompt revisar-pr disponible al escribir / en el prompt input, y el recurso config://actual accesible por su URI. Es la puerta a construir flujos internos de empresa que otros compañeros puedan consumir sin tocar codigo.

Pasar del transporte stdio al transporte HTTP

Si quieres que varios desarrolladores compartan el mismo servidor o desplegarlo en un contenedor, cambia el transporte a HTTP con SSE. Con FastMCP es trivial:

def main() -> None:
    mcp.run(transport="http", host="0.0.0.0", port=8765)

Y del lado cliente registras la URL en vez del comando:

claude mcp add mi-mcp-remoto \
  --scope user \
  --transport http \
  --url http://mi-servidor.local:8765/sse

Añade autenticacion antes de exponerlo fuera de tu LAN. Un simple middleware con token bearer basta para uso interno; para produccion seria, ponlo detras de un reverse proxy con TLS y OAuth.

Errores comunes y como resolverlos

Recopilamos los fallos que aparecen mas de una vez al configurar MCP:

• "MCP server X failed to start" al abrir Claude Code. Casi siempre es que el comando no existe en el PATH del proceso hijo. Prueba a poner la ruta absoluta al binario (/usr/bin/npx, /home/tu/.local/bin/uvx) o edita ~/.config/claude/mcp.json a mano.
• Timeout de conexion. El servidor tarda mas de 30 s en devolver el handshake. Suele ser un npx descargando dependencias por primera vez. Ejecuta el comando en una terminal aparte para que cachee y vuelve a intentar.
• "Permission denied" al leer archivos. El servidor filesystem no puede salir del directorio raiz que le diste. Anade mas rutas al comando add o usa un directorio padre comun.
• GitHub responde 401. El token expiro o le falta el scope repo. Regeneralo en la configuracion de GitHub y actualiza la variable de entorno.
• Puppeteer no encuentra Chromium en un contenedor Docker. Anade PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium al registro con --env.
• Cambios en el JSON no se aplican. Claude Code lee mcp.json al arrancar. Sal (/exit) y vuelve a entrar para forzar recarga.
• Herramientas duplicadas entre servidores. Si dos MCP registran una tool con el mismo nombre (por ejemplo read_file en filesystem y en un wrapper propio), Claude Code prefija con el nombre del servidor. Si aun asi hay conflicto, renombra en tu servidor propio o carga solo uno por sesion con --scope local.
• Consumo de tokens fuera de control. Un servidor mal diseñado puede devolver 200 KB de JSON por llamada y agotar el contexto. Limita respuestas con paginacion o parametros max_results, y monitoriza con claude cost despues de cada sesion pesada.

Depuracion avanzada con inspectores

Cuando lo anterior no basta, el equipo de Anthropic mantiene @modelcontextprotocol/inspector, una interfaz web que arranca con npx @modelcontextprotocol/inspector uvx mcp-server-sqlite --db-path ./ventas.db y permite invocar herramientas manualmente, ver el esquema JSON de cada tool y probar respuestas sin pasar por Claude. Es la manera mas rapida de saber si el bug esta en el servidor o en el cliente. Recomendado tenerlo instalado global antes de compartir un servidor con el equipo.

Hardware recomendado para trabajar con Claude Code y MCP

El flujo con MCP se apoya en muchas ventanas abiertas: terminal, editor, navegador con la docu, dashboards de GitHub. Con un solo monitor y una silla mala, la productividad cae en picado. Recomendaciones probadas que rotamos en la redaccion de Arkaia:

• Silla Secretlab TITAN Evo (Stealth): reclinable, reposabrazos 4D, cojin magnetico, soporte lumbar 4 vias. Sesiones de 6 horas frente a la terminal sin dolor de espalda. Ver precio actual en Amazon.
• Silla Razer Iskur V2: alternativa con soporte lumbar adaptativo integrado y tapizado EPU. Buena opcion para quien se apoya mucho en el respaldo. Ver precio actual en Amazon.
• Silla DRIFT DR35: entrada media con reclinable 135 grados y cuero sintetico transpirable. Relacion calidad-precio destacada para setups domesticos. Ver precio actual en Amazon.
• Monitor portatil ViewSonic VX1655-4K-OLED (15,6" 4K UHD): panel OLED, USB-C 60 W, Mini HDMI. Ideal para conectar al portatil de trabajo cuando estas fuera de casa y quieres una segunda pantalla para el terminal MCP. Ver precio actual en Amazon.
• Monitor portatil Arzopa Z3FC 16,1" 2,5K 180 Hz: resolucion QHD, 107% sRGB, HDR10. Alternativa con mejor tasa de refresco para quien alterna programacion y juego. Ver precio actual en Amazon.
• Monitor portatil ASUS ROG Strix XG16AHP-W (15,6" 144 Hz): G-Sync, tripode ROG y funda incluidos. Muy solido para quien trabaja con Claude Code mientras esta de viaje. Ver precio actual en Amazon.

Comparativa con alternativas: Cursor y Cline

Claude Code no es la unica herramienta que soporta MCP. Cursor y Cline (fork de Claude Dev para VS Code) tambien implementan el protocolo. La eleccion depende de tu flujo:

En Arkaia usamos Claude Code para todo lo que sea automatizacion, refactor grande o pipelines de datos, y VS Code con Cline como editor cuando queremos ver mas contexto visual. Los MCP registrados en ~/.config/claude/mcp.json se pueden reutilizar exportandolos al formato de Cline con dos comandos de jq. Si te interesa esta parte, avisanos en comentarios y publicamos el script.

Buenas practicas para vivir con MCP

Un ultimo bloque de consejos operativos, aprendidos a base de romper cosas:

• Un servidor por responsabilidad. No metas GitHub, GitLab y Bitbucket en un mismo wrapper; separa. Depurar es mucho mas facil.
• Usa scopes correctamente. user para lo global, project para el repo actual, local para experimentos de un rato.
• Versiona .claude/mcp.json en Git (sin tokens). Facilita que tu equipo tenga la misma configuracion.
• Revisa claude mcp logs cuando algo falla; el mensaje del servidor suele ser mas util que el error del cliente.
• Mantente al dia. El SDK y los servidores oficiales cambian rapido; suscribete al feed de releases del repositorio modelcontextprotocol/servers.

Preguntas frecuentes (FAQ)

Conclusion

Con estos seis pasos ya tienes un stack MCP realista: filesystem para leer y escribir codigo, GitHub para gestionar tu repo, SQLite para explorar datos, Puppeteer para navegar la web y un servidor Python propio para lo que no cubran los oficiales. Los tres primeros los puedes tener funcionando en 10 minutos; los otros tres en menos de una hora. La inversion se paga la primera vez que Claude Code te resuelve una tarea entera sin pedir permiso a mitad para leer un archivo.

Actualiza tu instalacion de Claude Code al menos una vez por semana: el ecosistema MCP esta madurando rapido y los servidores oficiales anaden herramientas nuevas casi cada release. En Arkaia iremos publicando tutoriales especificos por servidor a medida que aparezcan piezas relevantes; suscribete al feed RSS para no perdertelos.