Local Dev MCP

Servidor MCP local para que un agente de IA trabaje con varios proyectos en una misma máquina Windows.

Local Dev MCP proporciona al cliente de IA acceso a proyectos locales, al sistema de archivos y a la ejecución de comandos a través de PowerShell. Una única instancia del servidor puede trabajar con varios repositorios ubicados en uno o más directorios raíz.

Docker no es una dependencia obligatoria. Los proyectos pueden usar Docker, Node.js, PHP, Python o cualquier otro stack instalado localmente.

Instalación

1. Instale Node.js

Local Dev MCP requiere Node.js versión 20 o superior.

Compruebe la versión actual:

node --version
npm --version

Si Node.js no está instalado, instale la versión LTS actual desde el sitio oficial de Node.js.

Después de la instalación, cierre y vuelva a abrir PowerShell o Windows Terminal.

2. Obtenga Local Dev MCP

Clone el repositorio:

git clone https://github.com/mfokusnik/LocalDevMCP
cd LocalDevMCP

O descargue el archivo del repositorio y descomprímalo en un directorio conveniente, por ejemplo:

C:\Tools\local-dev-mcp

3. Realice la configuración inicial

Ejecute:

FIRST_RUN.cmd

El script automáticamente:

• comprobará la presencia de Node.js;

• solicitará el directorio raíz con los proyectos locales;

• creará config.local.json;

• instalará las dependencias npm;

• comprobará TypeScript;

• iniciará el servidor MCP.

Por ejemplo, si los proyectos del empleado se encuentran aquí:

C:\Users\User\Documents\GitHub

debe indicar este directorio en el primer inicio.

Otro empleado puede tener una ruta diferente:

D:\Projects

o:

C:\Development

La configuración se almacena localmente y no se incluye en Git.

4. Verifique el inicio

Después de un inicio exitoso, abra:

http://127.0.0.1:7676/health

Respuesta esperada:

{
  "ok": true,
  "name": "local-dev-mcp",
  "version": "0.1.0",
  "mcp": "http://127.0.0.1:7676/mcp"
}

Endpoint MCP:

http://127.0.0.1:7676/mcp

5. Conecte el cliente MCP

En el túnel MCP local que utilice, indique:

http://127.0.0.1:7676/mcp

Después de la conexión, el cliente de IA tendrá acceso a las herramientas MCP registradas.

6. Verifique la interfaz MCP

Con el servidor en ejecución, ejecute:

SMOKE_TEST.cmd

o:

npm run smoke

La prueba debe conectarse correctamente al endpoint MCP y devolver la lista de herramientas disponibles.

Related MCP server: Windows-MCP

Inicios posteriores

Después de la primera instalación, no se requiere una nueva configuración.

Para iniciar el servidor, use:

START.cmd

o:

npm run dev

La configuración local se guarda en:

config.local.json

Para cambiar el directorio de proyectos, puede editar este archivo manualmente o volver a ejecutar la configuración inicial.

Funcionalidades

• detección automática de proyectos en uno o más directorios raíz;

• selección del proyecto activo por nombre o alias;

• operaciones de archivos dentro del proyecto seleccionado;

• ejecución de comandos de PowerShell con el directorio de trabajo del proyecto seleccionado;

• detección básica del stack utilizado;

• verificación de disponibilidad de herramientas CLI locales;

• trabajo con Git y GitHub CLI a través del shell local;

• endpoint MCP HTTP Streamable;

• endpoint local de verificación de salud;

• protección de las operaciones MCP de archivos para que no salgan del proyecto activo.

Se admite la detección automática de las siguientes tecnologías y herramientas:

• Git;

• Node.js;

• PHP / Composer;

• Laravel;

• Docker / Docker Compose;

• Python;

• Go;

• Rust.

Arquitectura

AI-клиент
    │
    │ MCP
    ▼
Local Dev MCP
    │
    ├── обнаружение проектов
    ├── выбор workspace
    ├── файловые операции
    └── PowerShell
            │
            ├── git
            ├── gh
            ├── docker
            ├── npm
            ├── composer
            ├── php / artisan
            ├── python
            └── другие локальные CLI

El servidor no implementa herramientas MCP separadas para cada framework o entorno de ejecución.

Comandos como:

npm test
php artisan test
docker compose ps
git status
gh pr create

se ejecutan a través de la herramienta universal shell.run.

Gracias a esto, el servidor MCP no depende del stack tecnológico de un proyecto específico.

Requisitos

Obligatorio:

• Windows 10 o Windows 11;

• Node.js 20 o superior;

• al menos un directorio local con proyectos.

Las herramientas adicionales se instalan solo si es necesario:

• Git;

• GitHub CLI;

• Docker Desktop;

• PHP;

• Composer;

• Python;

• otras CLI y runtimes utilizados por los proyectos.

Docker no es necesario para que funcione Local Dev MCP.

Primer inicio

1. Clone o descomprima el proyecto

Por ejemplo:

C:\Tools\local-dev-mcp

2. Ejecute la configuración inicial

FIRST_RUN.cmd

El script:

1. comprobará la presencia de Node.js;

2. solicitará la ruta al directorio de proyectos;

3. creará el archivo de configuración local;

4. instalará las dependencias npm;

5. realizará la verificación de TypeScript;

6. iniciará el servidor MCP.

Por defecto se sugiere la ruta:

%USERPROFILE%\Documents\GitHub

Si es necesario, puede indicar otra:

D:\Projects

3. Verifique el inicio

Abra:

http://127.0.0.1:7676/health

Respuesta esperada:

{
  "ok": true,
  "name": "local-dev-mcp",
  "version": "0.1.0",
  "mcp": "http://127.0.0.1:7676/mcp"
}

Endpoint MCP:

http://127.0.0.1:7676/mcp

Por defecto, el servidor escucha solo en 127.0.0.1 y no se publica directamente en la red local o en Internet.

4. Conecte el cliente MCP

En el túnel MCP local u otro cliente compatible, indique:

http://127.0.0.1:7676/mcp

5. Realice una prueba de humo

Con el servidor en ejecución:

SMOKE_TEST.cmd

o:

npm run smoke

La prueba verifica la conexión a MCP y muestra la lista de herramientas registradas.

Inicio normal

Después de la configuración inicial:

START.cmd

o:

npm run dev

Configuración

La configuración local se almacena en:

config.local.json

El archivo está excluido de Git mediante .gitignore y está destinado a la configuración de una estación de trabajo específica.

Ejemplo:

{
  "roots": [
    "C:\\Users\\YourName\\Documents\\GitHub"
  ],
  "scanDepth": 1,
  "host": "127.0.0.1",
  "port": 7676,
  "mcpPath": "/mcp",
  "shell": {
    "executable": "powershell.exe",
    "timeoutMs": 120000,
    "maxOutputChars": 200000
  },
  "skipDirectories": [
    ".git",
    "node_modules",
    "vendor",
    ".next",
    "dist",
    "build"
  ],
  "projects": []
}

Varios directorios raíz

{
  "roots": [
    "C:\\Users\\YourName\\Documents\\GitHub",
    "D:\\Work",
    "D:\\Experiments"
  ]
}

Cada directorio se escanea de forma independiente.

Profundidad de escaneo

Si la estructura de proyectos es anidada:

D:\Work
├── clients
│   ├── project-a
│   └── project-b
└── internal
    └── project-c

puede aumentar:

{
  "scanDepth": 2
}

El valor máximo en la versión actual es 5.

Adición explícita de un proyecto y alias

Los proyectos se pueden agregar manualmente:

{
  "projects": [
    {
      "name": "sample-app",
      "path": "D:\\Projects\\sample-app",
      "aliases": [
        "sample",
        "app"
      ]
    }
  ]
}

Después de esto, el proyecto se puede seleccionar tanto por su nombre principal como por su alias.

Detección de proyectos

Un directorio se considera un proyecto si contiene al menos uno de los marcadores admitidos:

.git
package.json
composer.json
artisan
compose.yml
compose.yaml
docker-compose.yml
docker-compose.yaml
Dockerfile
pyproject.toml
requirements.txt
go.mod
Cargo.toml

Después de determinar que un directorio es un proyecto, el escaneo de sus subcarpetas se detiene.

Esto evita que las dependencias internas y los directorios de servicio se definan como workspaces separados.

Herramientas MCP

projects.list

Devuelve la lista de proyectos detectados y configurados explícitamente.

projects.select

Selecciona el proyecto activo por nombre o alias.

Ejemplo:

Пользователь:
Работаем с sample-app

AI:
projects.select({ "name": "sample-app" })

En la respuesta, el servidor devuelve:

• la ruta absoluta del proyecto;

• el stack detectado;

• la rama Git actual;

• el estado del working tree;

• la lista de herramientas CLI locales disponibles.

projects.current

Devuelve el proyecto activo actual y su estado.

fs.list

Muestra el contenido de los directorios dentro del proyecto activo.

fs.read

Lee archivos UTF-8.

Se admite la lectura de un rango de líneas.

fs.write

Crea un archivo nuevo o sobrescribe completamente uno existente.

fs.replace

Realiza un reemplazo exacto de texto en un archivo.

Se admite el reemplazo de una o todas las coincidencias.

fs.move

Mueve o renombra un archivo o directorio dentro del proyecto activo.

fs.delete

Elimina un archivo o directorio dentro del proyecto activo.

La eliminación del directorio raíz del proyecto activo a través de esta herramienta está prohibida.

shell.run

Ejecuta un comando de PowerShell con el directorio de trabajo del proyecto activo.

Ejemplos:

git status

git switch -c feature/example

npm test

php artisan test

docker compose ps

docker compose exec app php artisan test

gh pr create

Las herramientas separadas docker.*, git.* o artisan.* no se implementan en la versión actual.

La interfaz universal para ejecutar comandos es el shell local.

Docker

Docker es una herramienta opcional.

Si Docker Desktop está instalado, el cliente de IA puede usar la CLI de Docker a través de shell.run.

Por ejemplo:

docker compose ps

o:

docker compose exec app npm test

Si Docker no está presente, el servidor MCP continúa funcionando sin restricciones para las demás herramientas.

Lo mismo se aplica a PHP, Composer, Python, GitHub CLI y otros runtimes.

Git y GitHub

Las operaciones de Git se realizan a través de la CLI de Git instalada localmente.

Por ejemplo:

git status
git diff
git switch -c feature/example
git commit

Con GitHub CLI instalado y autorizado, están disponibles las operaciones a través de gh:

gh pr create
gh pr view
gh issue list
gh issue comment

Local Dev MCP no almacena tokens de GitHub y utiliza la autorización local existente.

Modelo de seguridad

Las herramientas MCP de archivos están limitadas al proyecto activo.

Los intentos de acceder a un archivo a través de una ruta que salga del workspace se bloquean.

Por ejemplo:

..\..\some-file.txt

no debería permitir que fs.read, fs.write u otras herramientas de archivos salgan del proyecto seleccionado.

Sin embargo, shell.run no es un sandbox.

El comando se ejecuta desde el directorio del proyecto activo:

cwd = active project

pero PowerShell técnicamente puede acceder a otros directorios y recursos locales si se indica directamente en el comando.

Por lo tanto, la versión actual está diseñada para un entorno de desarrollo local de confianza:

один сотрудник
=
один локальный MCP
=
одна рабочая станция

Estado del proyecto activo

El proyecto seleccionado se almacena en la memoria del proceso MCP.

Después de reiniciar el servidor, es necesario volver a seleccionar el proyecto.

La versión actual no está diseñada para el trabajo simultáneo de varios usuarios independientes a través de una única instancia del servidor.

Estructura del proyecto

local-dev-mcp/
├── src/
│   ├── index.ts
│   ├── server.ts
│   ├── config.ts
│   ├── projects.ts
│   ├── fs-tools.ts
│   ├── shell.ts
│   ├── smoke.ts
│   └── types.ts
├── scripts/
│   └── setup.ps1
├── FIRST_RUN.cmd
├── START.cmd
├── SMOKE_TEST.cmd
├── config.example.json
├── package.json
└── tsconfig.json

Comandos de desarrollo

Instalación de dependencias:

npm install

Inicio:

npm run dev

Verificación de tipos:

npm run check

Compilación:

npm run build

Ejecución de la versión compilada:

npm start

Prueba de humo:

npm run smoke

Limitaciones de la versión actual

En la versión actual no están disponibles:

• interfaz web;

• sistema de usuarios;

• base de datos;

• ACL para comandos de shell individuales;

• confirmación de comandos potencialmente peligrosos a nivel de servidor;

• contenedor Docker para el propio MCP;

• perfiles de runtime separados;

• guardado del proyecto activo después de un reinicio;

• endpoint remoto público;

• modo multiusuario.

Estas funcionalidades pueden agregarse según sea necesario.

Diagnóstico

Node.js no encontrado

Compruebe:

node --version
npm --version

Se requiere Node.js 20 o superior.

MCP iniciado, pero el cliente no se conecta

Primero verifique:

http://127.0.0.1:7676/health

Si /health no está disponible, el problema está en el lado del MCP local.

Si /health funciona, verifique el endpoint MCP:

http://127.0.0.1:7676/mcp

y la configuración del túnel MCP utilizado.

Puerto 7676 ocupado

Cambie el puerto en config.local.json:

{
  "port": 7677
}

Después, use el nuevo puerto en el cliente MCP.

El proyecto no se detecta

Compruebe:

1. si el proyecto está dentro de uno de los roots;

2. si el directorio contiene un marcador de proyecto admitido;

3. si el valor de scanDepth es suficiente;

4. si es necesario, agregue el proyecto explícitamente a través de projects.

Tecnologías

• TypeScript;

• Node.js;

• Model Context Protocol;

• SDK oficial de MCP para TypeScript.

Documentación:

https://modelcontextprotocol.io/
https://github.com/modelcontextprotocol/typescript-sdk