Cómo crear un servidor MCP local para Claude: archivos, comandos, capturas de pantalla y control de aplicaciones

Claude se vuelve mucho más útil cuando deja de ser solo una interfaz de chat.

Un servidor MCP local permite que Claude interactúe con tu máquina real: archivos locales, comandos aprobados, capturas de pantalla y apertura de aplicaciones. La parte importante no es el acceso directo, sino el acceso controlado.

En esta guía, construiremos un servidor MCP local para Claude que sea práctico, acotado y lo suficientemente seguro para usar en flujos de trabajo reales.

Una nota rápida antes de construir nada

Este artículo evita intencionalmente la versión irresponsable de "control de computadora".

No vamos a darle a Claude acceso ilimitado al shell, autoridad total sobre el sistema de archivos ni permiso para mutar tu máquina sin protecciones. La forma más rápida de construir un mal servidor MCP local es exponer una herramienta gigante run_anything() y llamarlo innovación.

El mejor patrón es:

• directorios en lista blanca
• comandos en lista blanca
• valores predeterminados seguros
• registros legibles para humanos
• respuestas explícitas
• separación clara entre herramientas de solo lectura y herramientas de acción

Si Claude puede hacerlo todo, has creado una demostración.

Si Claude puede hacer las cosas correctas de forma segura, has creado algo utilizable.

Por qué vale la pena aprender esta arquitectura

El valor de un servidor MCP local no es la novedad. Es la reducción de fricción.

Sin una capa de herramientas local, tu flujo de trabajo se ve así:

1. Preguntar a Claude qué hacer
2. Copiar la respuesta
3. Abrir la carpeta tú mismo
4. Ejecutar el comando tú mismo
5. Tomar la captura de pantalla tú mismo
6. Pegar el resultado de nuevo en el chat

Con un servidor MCP local, ese ciclo se vuelve drásticamente más ajustado. Claude puede inspeccionar el contexto que necesita, usar herramientas con alcance limitado y devolver una respuesta basada en el estado real de tu máquina.

Eso es útil para:

• flujos de trabajo de desarrollo
• inspección de registros
• operaciones de contenido
• procesos de investigación
• automatización de escritorio
• tareas administrativas repetitivas

Y como la capa de herramientas es tuya, tú eliges exactamente dónde se detiene el modelo.

¿Quieres aprender sobre IA y mantenerte a la vanguardia en tu carrera?

Comparto:

Más de 1000 prompts de IA

Herramientas y automatizaciones de IA

Consejos de carrera y crecimiento en LinkedIn

Recursos seleccionados de tecnología y productividad

Suscríbete aquí:

https://bytebuilders.beehiiv.com/subscribe

Sígueme para más consejos de IA

👇

El diseño que vamos a construir

Vamos a construir un servidor local con cinco herramientas:

1. list_files — ver qué existe dentro de las carpetas aprobadas
2. read_file — abrir archivos de texto seguros
3. run_command — ejecutar un pequeño conjunto de comandos locales aprobados
4. take_screenshot — guardar una captura de pantalla en una ubicación conocida
5. open_target — abrir una aplicación, archivo, carpeta o URL

Ese alcance es deliberado.

Es suficiente para que Claude sea significativamente útil en una máquina local sin caer en una automatización insegura de propósito general.

El modelo mental debería ser este:

Claude → Cliente MCP → Servidor MCP local → Herramientas limitadas → Sistema operativo

Claude nunca debería hablar directamente con tu sistema operativo. Tu servidor MCP es el plano de control en el medio.

La pila tecnológica

Para una construcción local, Python es una opción limpia porque el SDK oficial de MCP está maduro, la abstracción FastMCP es concisa y Python sigue siendo el lenguaje más fácil para scripts de sistema de archivos, subprocesos y automatización de escritorio 4 2.

Usaremos:

• Python 3.11+
• mcp[cli] para el entorno de ejecución del servidor MCP
• mss para capturas de pantalla multiplataforma
• módulos de la biblioteca estándar para acceso a archivos, llamadas a subprocesos y manejo del SO

Configura un nuevo proyecto:

1mkdir local-mcp-server
2cd local-mcp-server
3uv init --python 3.11
4uv add "mcp[cli]>=1.0,<2.0" "mss>=9.0,<10.0"

El estilo FastMCP basado en decoradores mantiene la capa del protocolo fuera de tu camino para que puedas concentrarte en la calidad de las herramientas en lugar del cableado 4 5.

Una estructura de proyecto simple funciona bien:

1mkdir local-mcp-server
2cd local-mcp-server
3uv init --python 3.11
4uv add "mcp[cli]>=1.0,<2.0" "mss>=9.0,<10.0"

No necesitas una arquitectura compleja para la versión 1. Lo que necesitas es claridad.

El servidor real

Crea server.py y comienza con una implementación basada en políticas.

1from __future__ import annotations
2
3import json
4import os
5import platform
6import shlex
7import subprocess
8from pathlib import Path
9from typing import Any
10
11import mss
12from mcp.server.fastmcp import FastMCP
13
14app = FastMCP("local-computer-control", json_response=True)
15
16HOME = Path.home()
17PROJECT_ROOT = Path(__file__).parent.resolve()
18CAPTURE_DIR = PROJECT_ROOT / "captures"
19CAPTURE_DIR.mkdir(exist_ok=True)
20
21ALLOWED_ROOTS = [
22    HOME / "Documents",
23    HOME / "Desktop",
24    PROJECT_ROOT,
25]
26
27ALLOWED_COMMANDS = {
28    "pwd",
29    "ls",
30    "git status",
31    "git diff --stat",
32    "python --version",
33    "node --version",
34    "npm --version",
35}
36
37READABLE_EXTENSIONS = {
38    ".txt",
39    ".md",
40    ".json",
41    ".py",
42    ".js",
43    ".ts",
44    ".tsx",
45    ".jsx",
46    ".yaml",
47    ".yml",
48    ".toml",
49    ".csv",
50    ".log",
51}
52
53def _resolve_path(raw_path: str) -> Path:
54    # Resuelve la ruta y verifica que esté dentro de los directorios permitidos
55    path = Path(raw_path).expanduser().resolve()
56    for root in ALLOWED_ROOTS:
57        root = root.resolve()
58        if path == root or root in path.parents:
59            return path
60    raise ValueError(f"Ruta no permitida: {path}")
61
62def _ensure_safe_command(command: str) -> str:
63    # Normaliza el comando y verifica que esté en la lista blanca
64    normalized = " ".join(shlex.split(command))
65    if normalized not in ALLOWED_COMMANDS:
66        raise ValueError(
67            "Comando no permitido. Agrégalo explícitamente a ALLOWED_COMMANDS si realmente lo necesitas."
68        )
69    return normalized
70
71@app.tool()
72def list_files(path: str = "~") -> dict[str, Any]:
73    """Lista los archivos y carpetas dentro de un directorio aprobado."""
74    target = _resolve_path(path)
75    if not target.is_dir():
76        raise ValueError(f"No es un directorio: {target}")
77
78    items = []
79    for child in sorted(target.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower())):
80        items.append(
81            {
82                "name": child.name,
83                "path": str(child),
84                "type": "directory" if child.is_dir() else "file",
85            }
86        )
87
88    return {
89        "path": str(target),
90        "count": len(items),
91        "items": items,
92    }
93
94@app.tool()
95def read_file(path: str, max_chars: int = 12000) -> dict[str, Any]:
96    """Lee un archivo de texto seguro desde una ubicación aprobada."""
97    target = _resolve_path(path)
98    if not target.is_file():
99        raise ValueError(f"No es un archivo: {target}")
100    if target.suffix.lower() not in READABLE_EXTENSIONS:
101        raise ValueError(f"Tipo de archivo no soportado: {target.suffix}")
102
103    content = target.read_text(encoding="utf-8", errors="replace")
104    truncated = len(content) > max_chars
105    content = content[:max_chars]
106
107    return {
108        "path": str(target),
109        "truncated": truncated,
110        "content": content,
111    }
112
113@app.tool()
114def run_command(command: str, cwd: str | None = None, timeout: int = 15) -> dict[str, Any]:
115    """Ejecuta un comando local permitido."""
116    safe_command = _ensure_safe_command(command)
117    working_dir = _resolve_path(cwd) if cwd else PROJECT_ROOT
118
119    completed = subprocess.run(
120        safe_command,
121        shell=True,
122        cwd=str(working_dir),
123        capture_output=True,
124        text=True,
125        timeout=timeout,
126    )
127
128    return {
129        "command": safe_command,
130        "cwd": str(working_dir),
131        "returncode": completed.returncode,
132        "stdout": completed.stdout.strip(),
133        "stderr": completed.stderr.strip(),
134    }
135
136@app.tool()
137def take_screenshot(name: str = "latest") -> dict[str, Any]:
138    """Toma una captura de pantalla y la guarda localmente."""
139    output_path = CAPTURE_DIR / f"{name}.png"
140
141    with mss.mss() as sct:
142        sct.shot(output=str(output_path))
143
144    return {
145        "saved": True,
146        "path": str(output_path),
147    }
148
149@app.tool()
150def open_target(target: str) -> dict[str, Any]:
151    """Abre un archivo, carpeta, aplicación o URL aprobado usando el SO local."""
152    system = platform.system().lower()
153
154    if target.startswith("http://") or target.startswith("https://"):
155        resolved = target
156    else:
157        resolved = str(_resolve_path(target))
158
159    if system == "darwin":
160        subprocess.run(["open", resolved], check=True)
161    elif system == "windows":
162        os.startfile(resolved)  # type: ignore[attr-defined]
163    else:
164        subprocess.run(["xdg-open", resolved], check=True)
165
166    return {
167        "opened": True,
168        "target": resolved,
169    }
170
171if __name__ == "__main__":
172    app.run(transport="stdio")

Este es un servidor compacto, pero la parte importante no es su longitud. La parte importante es la forma de la interfaz:

• cada herramienta tiene un trabajo muy claro
• cada herramienta devuelve datos estructurados
• la ejecución de comandos está controlada
• el acceso a archivos está enraizado
• las capturas de pantalla van a una carpeta conocida

Eso es exactamente lo que quieres en un servidor MCP local.

Por qué estas herramientas están diseñadas así

El contenido avanzado sobre herramientas de agentes nunca debería limitarse a "aquí está el código". La forma de la herramienta es la verdadera lección.

list_files

Esta herramienta le da a Claude una superficie de descubrimiento segura. Debería poder responder preguntas como:

• ¿Qué hay en esta carpeta del proyecto?
• ¿Qué notas existen en Documentos?
• ¿Ya hay un archivo de registro que pueda inspeccionar?

Pero no debería convertirse en un rastreador recursivo de todo el disco.

read_file

Esta suele ser la herramienta local más útil de todas. Un gran porcentaje del trabajo real sigue estando oculto en notas locales de Markdown, registros, CSVs, documentos y archivos de proyecto.

El límite max_chars importa. Los archivos grandes son un problema de contexto y latencia. Devolver todo el contenido de un archivo de registro gigante rara vez es útil.

run_command

Aquí es donde la mayoría de la gente se vuelve descuidada.

El patrón seguro no es "permitir acceso al shell y luego esperar lo mejor". El patrón seguro es "permitir un pequeño conjunto de comandos exactos y revisables". Por eso el ejemplo usa una lista blanca estricta.

take_screenshot

Una herramienta de captura de pantalla es valiosa porque permite que Claude participe en flujos de trabajo de escritorio. Incluso si tu primera versión solo guarda la imagen en el disco, eso ya es útil para informes, depuración de UI, captura de documentación y traspasos estructurados.

open_target

El control de aplicaciones no necesita comenzar con automatización de GUI. Para muchos flujos de trabajo, "abrir la carpeta, archivo o URL correcta" es suficiente.

Esa es una versión 1 más duradera que pretender que necesitas automatización completa del cursor desde el primer día.

Conectando el servidor a Claude

Los servidores MCP locales normalmente se ejecutan a través de stdio, lo que significa que Claude inicia el proceso localmente y se comunica directamente a través de stdin/stdout. Para un servidor de control de computadora local, ese es el valor predeterminado correcto porque evita exposición innecesaria a la red 4 5.

Claude Desktop es compatible con servidores MCP locales a través de configuración, donde inicia el proceso del servidor por ti. En la práctica, usar rutas absolutas para el intérprete y el script es la configuración menos frágil porque los entornos de aplicaciones GUI locales suelen ser más estrictos que tu terminal 2.

Una configuración mínima se ve así:

1{
2  "mcpServers": {
3    "local-computer-control": {
4      "command": "/ruta/absoluta/hacia/python",
5      "args": [
6        "/ruta/absoluta/hacia/local-mcp-server/server.py"
7      ]
8    }
9  }
10}

Si prefieres uv, también está bien:

1{
2  "mcpServers": {
3    "local-computer-control": {
4      "command": "/ruta/absoluta/hacia/uv",
5      "args": [
6        "--directory",
7        "/ruta/absoluta/hacia/local-mcp-server",
8        "run",
9        "python",
10        "server.py"
11      ]
12    }
13  }
14}

Después de guardar la configuración y reiniciar Claude, las herramientas del servidor deberían aparecer en la lista de herramientas MCP locales. La configuración local-MCP de Claude Desktop está construida exactamente alrededor de este modelo: iniciar un proceso local, conectar a través de stdio y exponer las herramientas al modelo 2 3.

Prompts que realmente son útiles para probar

Una vez que el servidor está conectado, no empieces con orquestación complicada. Comienza con comprobaciones directas y aburridas.

Prueba prompts como:

• "Lista los archivos en mi carpeta de Escritorio."
• "Lee ~/Documents/todo.md y resume las tres prioridades principales."
• "Ejecuta git status en mi carpeta de proyecto local y explica qué cambió."
• "Toma una captura de pantalla llamada workspace-check."
• "Abre el README de mi proyecto."

Si esos flujos simples funcionan de manera consistente, tienes un servidor que vale la pena expandir.

Si no funcionan, agregar más herramientas solo ocultará los problemas reales.

Donde los servidores MCP locales se vuelven genuinamente valiosos

El caso de uso obvio es el desarrollo, pero ese es solo un carril.

Flujo de trabajo del desarrollador

Claude puede:

• inspeccionar una carpeta de repositorio
• leer un archivo de configuración
• ejecutar git status
• capturar una captura de pantalla de un estado de error
• abrir el directorio del proyecto

Eso ya elimina mucho cambio de contexto.

Flujo de trabajo de investigación

Claude puede:

• listar carpetas de investigación
• abrir y resumir notas de Markdown
• leer CSVs estructurados
• guardar capturas de pantalla de herramientas o paneles
• abrir archivos fuente o enlaces de navegador

Flujo de trabajo de contenido

Claude puede:

• escanear una carpeta de borradores
• leer ideas de publicaciones existentes
• capturar una captura de pantalla de una referencia de diseño
• abrir el archivo de escritura o URL correcta
• ejecutar un comando limitado que genere un artefacto de compilación o exportación de borrador

Flujo de trabajo de operaciones

Claude puede:

• inspeccionar registros de directorios aprobados
• ejecutar un comando de diagnóstico de solo lectura
• abrir la carpeta o enlace del panel relevante
• guardar una captura de pantalla como evidencia

Este es el verdadero punto de la arquitectura: no "control de computadora" como una proeza, sino compresión del flujo de trabajo.

La capa de seguridad es el producto

Esta es la sección que demasiados artículos técnicos trivializan.

La parte peligrosa del MCP local no es el protocolo. Es un mal diseño de permisos.

Si quieres que este servidor sea utilizable más allá de una demostración, construye el modelo de seguridad desde el principio.

Usa listas blancas de directorios

Claude solo debería poder ver rutas que apruebes explícitamente. Por eso _resolve_path() es el núcleo de las herramientas de archivos.

Usa listas blancas de comandos

Nunca expongas la ejecución arbitraria de shell en una primera versión. Comienza con comandos exactos que puedas auditar línea por línea.

Separa las herramientas de lectura de las herramientas de acción

Las herramientas de solo lectura deberían ser la opción predeterminada. Las herramientas de acción deberían introducirse deliberadamente.

Registra todo

Incluso un registro JSON simple de solo añadir mejora drásticamente la depuración y la confianza.

Agrega una capa de confirmación para escrituras

Si luego agregas write_file, move_file o delete_file, haz que esas herramientas requieran un segundo token de confirmación o mantenlas deshabilitadas por defecto.

Considera un modo de simulación

Para herramientas que toman acciones, el modo de simulación está infravalorado. Permite que Claude explique lo que haría antes de hacerlo.

Ejecuta bajo un usuario restringido cuando sea posible

Si hablas en serio sobre la automatización local, no le des a tu servidor MCP más privilegios del SO de los que necesita.

Una regla general útil:

• Nivel 1: herramientas de solo lectura
• Nivel 2: acciones de bajo riesgo como abrir archivo / abrir aplicación
• Nivel 3: acciones de escritura confirmadas
• Nivel 4: acciones destructivas que probablemente no deberías exponer casualmente

La mayoría de la gente nunca necesita el Nivel 4.

Qué mejorar después de la versión 1

Una primera versión sólida gana el derecho de volverse más capaz.

Una vez que el servidor básico es estable, las siguientes mejoras sensatas son:

1. Archivo de política centralizado

Mueve tus reglas a config/policy.json para que los cambios sean declarativos.

Ejemplo:

1{
2  "allowed_roots": [
3    "~/Documents",
4    "~/Desktop",
5    "./"
6  ],
7  "allowed_commands": [
8    "pwd",
9    "ls",
10    "git status",
11    "git diff --stat",
12    "python --version"
13  ]
14}

1. Registro estructurado

Registra llamadas a herramientas, marcas de tiempo, argumentos y resultados en logs/server.log o un archivo JSONL.

1. Ejecución de comandos más segura

En lugar de una sola herramienta de comando genérica, divide los comandos en herramientas más específicas como:

• git_status
• show_current_directory
• list_project_files

Eso facilita la elección de herramientas para Claude y la seguridad para ti.

1. Mejor manejo de capturas de pantalla

Puedes evolucionar de "guardar una captura de pantalla en el disco" a:

• capturas con marca de tiempo
• captura de ventana activa
• captura de región
• reglas de retención de archivos

1. Adaptadores de automatización específicos del SO

En macOS, puedes agregar AppleScript o Accesos directos más adelante. En Windows, PowerShell o Automatización de UI. En Linux, lanzadores específicos del escritorio y herramientas de ventana.

Pero eso debería venir después de que el núcleo local aburrido sea confiable.

Errores comunes que la gente comete con servidores MCP locales

Los errores son predecibles.

Error 1: Demasiado poder, demasiado pronto

A la gente le encanta la idea del control total de la computadora. Odian depurarlo. Empieza más pequeño.

Error 2: Nombres de herramientas vagos

Si los nombres de tus herramientas son ambiguos, Claude las usará mal. Sé explícito.

Malo:

• system_action
• computer_control

Mejor:

• list_files
• read_file
• run_command
• take_screenshot
• open_target

Error 3: Salidas no estructuradas

Un blob de texto mixto es más difícil de razonar para Claude que un objeto JSON limpio.

Error 4: Sin registro

Si una herramienta falla y no puedes ver por qué, el sistema se convierte en adivinanzas.

Error 5: Tratar al modelo como la capa de control

Claude es la capa de razonamiento. Tu servidor debe seguir siendo la capa de aplicación de reglas.

Esa distinción es innegociable.

Qué hace esta arquitectura mejor que la automatización simple

La automatización de escritorio tradicional suele ser una de dos cosas:

• scripts de GUI frágiles
• scripts aislados que requieren que un humano sepa exactamente cuándo ejecutarlos

Un servidor MCP local cambia eso porque Claude puede decidir qué herramienta usar según la solicitud del usuario y el contexto disponible.

Eso significa que no solo estás automatizando un comando. Estás construyendo una capa de capacidad local sobre la que el modelo puede razonar.

Por eso MCP se siente importante. No es simplemente otro patrón de integración. Es una forma más limpia de exponer el uso de herramientas al modelo sin codificar cada flujo de trabajo posible en la capa de aplicación.

Los límites que debes respetar

Incluso un buen servidor MCP local tiene limitaciones reales.

• La automatización de escritorio puede ser impredecible entre sistemas operativos.
• Las capturas de pantalla son útiles, pero no mágicas.
• Abrir aplicaciones es fácil; la manipulación confiable de la UI es más difícil.
• El acceso genérico al shell es peligroso.
• La inflación de contexto es real si las salidas de las herramientas son demasiado grandes.
• La aprobación humana sigue siendo valiosa para cualquier cosa importante.

En otras palabras: no confundas "el modelo puede tomar acciones" con "el modelo debería actuar sin supervisión".

El patrón más valioso es el control colaborativo, no la autonomía ciega.