Local Dev MCP

Lokaler MCP-Server für die Arbeit eines KI-Agenten mit mehreren Projekten auf einem Windows-Rechner.

Local Dev MCP bietet dem KI-Clienten Zugriff auf lokale Projekte, das Dateisystem und die Ausführung von Befehlen über PowerShell. Eine Serverinstanz kann gleichzeitig mit mehreren Repositorys arbeiten, die sich in einem oder mehreren Stammverzeichnissen befinden.

Docker ist keine zwingende Abhängigkeit. Projekte können Docker, Node.js, PHP, Python oder einen anderen lokal installierten Stack verwenden.

Installation

1. Node.js installieren

Für Local Dev MCP ist Node.js Version 20 oder neuer erforderlich.

Überprüfen Sie die aktuelle Version:

node --version
npm --version

Wenn Node.js nicht installiert ist, installieren Sie die aktuelle LTS-Version von der offiziellen Node.js-Website.

Nach der Installation schließen und öffnen Sie PowerShell oder Windows Terminal erneut.

2. Local Dev MCP abrufen

Klonen Sie das Repository:

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

Oder laden Sie das Repository-Archiv herunter und entpacken Sie es in ein beliebiges Verzeichnis, zum Beispiel:

C:\Tools\local-dev-mcp

3. Ersteinrichtung durchführen

Führen Sie aus:

FIRST_RUN.cmd

Das Skript wird automatisch:

• das Vorhandensein von Node.js prüfen;

• das Stammverzeichnis mit lokalen Projekten abfragen;

• config.local.json erstellen;

• npm-Abhängigkeiten installieren;

• TypeScript prüfen;

• den MCP-Server starten.

Wenn sich die Projekte des Mitarbeiters beispielsweise hier befinden:

C:\Users\User\Documents\GitHub

muss dieses Verzeichnis beim ersten Start angegeben werden.

Bei einem anderen Mitarbeiter kann der Pfad beliebig sein:

D:\Projects

oder:

C:\Development

Die Konfiguration wird lokal gespeichert und gelangt nicht in Git.

4. Start überprüfen

Nach erfolgreichem Start öffnen Sie:

http://127.0.0.1:7676/health

Erwartete Antwort:

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

MCP-Endpunkt:

http://127.0.0.1:7676/mcp

5. MCP-Client verbinden

Geben Sie im verwendeten lokalen MCP-Tunnel an:

http://127.0.0.1:7676/mcp

Nach der Verbindung erhält der KI-Client Zugriff auf die registrierten MCP-Tools.

6. MCP-Schnittstelle prüfen

Führen Sie bei laufendem Server aus:

SMOKE_TEST.cmd

oder:

npm run smoke

Der Test sollte sich erfolgreich mit dem MCP-Endpunkt verbinden und eine Liste der verfügbaren Tools zurückgeben.

Related MCP server: Windows-MCP

Spätere Starts

Nach der ersten Installation ist keine erneute Einrichtung erforderlich.

Verwenden Sie zum Starten des Servers:

START.cmd

oder:

npm run dev

Die lokale Konfiguration wird gespeichert unter:

config.local.json

Um das Projektverzeichnis zu ändern, können Sie diese Datei manuell bearbeiten oder die Ersteinrichtung erneut ausführen.

Funktionen

• automatische Erkennung von Projekten in einem oder mehreren Stammverzeichnissen;

• Auswahl des aktiven Projekts nach Name oder Alias;

• Dateioperationen innerhalb des ausgewählten Projekts;

• Ausführung von PowerShell-Befehlen mit dem Arbeitsverzeichnis des ausgewählten Projekts;

• grundlegende Erkennung des verwendeten Stacks;

• Prüfung der Verfügbarkeit lokaler CLI-Tools;

• Arbeit mit Git und GitHub CLI über die lokale Shell;

• Streamable-HTTP-MCP-Endpunkt;

• lokaler Health-Check-Endpunkt;

• Schutz von Datei-MCP-Operationen vor dem Verlassen des aktiven Projekts.

Die automatische Erkennung der folgenden Technologien und Tools wird unterstützt:

• Git;

• Node.js;

• PHP / Composer;

• Laravel;

• Docker / Docker Compose;

• Python;

• Go;

• Rust.

Architektur

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

Der Server implementiert keine separaten MCP-Tools für jedes Framework oder jede Laufzeitumgebung.

Befehle wie:

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

werden über das universelle Tool shell.run ausgeführt.

Dadurch ist der MCP-Server unabhängig vom Technologie-Stack des jeweiligen Projekts.

Anforderungen

Erforderlich:

• Windows 10 oder Windows 11;

• Node.js 20 oder neuer;

• mindestens ein lokales Verzeichnis mit Projekten.

Zusätzliche Tools werden nur bei Bedarf installiert:

• Git;

• GitHub CLI;

• Docker Desktop;

• PHP;

• Composer;

• Python;

• andere CLI und Laufzeitumgebungen, die von den Projekten verwendet werden.

Docker wird für den Betrieb von Local Dev MCP nicht benötigt.

Erster Start

1. Projekt klonen oder entpacken

Zum Beispiel:

C:\Tools\local-dev-mcp

2. Ersteinrichtung starten

FIRST_RUN.cmd

Das Skript:

1. prüft das Vorhandensein von Node.js;

2. fragt den Pfad zum Projektverzeichnis ab;

3. erstellt eine lokale Konfigurationsdatei;

4. installiert npm-Abhängigkeiten;

5. führt eine TypeScript-Prüfung durch;

6. startet den MCP-Server.

Standardmäßig wird folgender Pfad vorgeschlagen:

%USERPROFILE%\Documents\GitHub

Bei Bedarf kann ein anderer angegeben werden:

D:\Projects

3. Start überprüfen

Öffnen Sie:

http://127.0.0.1:7676/health

Erwartete Antwort:

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

MCP-Endpunkt:

http://127.0.0.1:7676/mcp

Standardmäßig lauscht der Server nur auf 127.0.0.1 und wird nicht direkt im lokalen Netzwerk oder Internet veröffentlicht.

4. MCP-Client verbinden

Geben Sie im lokalen MCP-Tunnel oder einem anderen kompatiblen Client an:

http://127.0.0.1:7676/mcp

5. Smoke-Test durchführen

Bei laufendem Server:

SMOKE_TEST.cmd

oder:

npm run smoke

Der Test prüft die Verbindung zum MCP und listet die registrierten Tools auf.

Normaler Start

Nach der Ersteinrichtung:

START.cmd

oder:

npm run dev

Konfiguration

Die lokale Konfiguration wird gespeichert unter:

config.local.json

Die Datei ist über .gitignore von Git ausgeschlossen und für die Einstellungen einer bestimmten Workstation gedacht.

Beispiel:

{
  "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": []
}

Mehrere Stammverzeichnisse

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

Jedes Verzeichnis wird unabhängig gescannt.

Scan-Tiefe

Wenn die Projektstruktur verschachtelt ist:

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

kann erhöht werden:

{
  "scanDepth": 2
}

Der Maximalwert in der aktuellen Version ist 5.

Explizites Hinzufügen von Projekten und Alias

Projekte können manuell hinzugefügt werden:

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

Danach kann das Projekt sowohl über den Hauptnamen als auch über den Alias ausgewählt werden.

Projekterkennung

Ein Verzeichnis gilt als Projekt, wenn es mindestens einen der unterstützten Marker enthält:

.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

Nachdem ein Verzeichnis als Projekt erkannt wurde, wird das Scannen seiner Unterordner beendet.

Dadurch werden interne Abhängigkeiten und Dienstverzeichnisse nicht als separate Workspaces erkannt.

MCP-Tools

projects.list

Gibt eine Liste der erkannten und explizit konfigurierten Projekte zurück.

projects.select

Wählt das aktive Projekt nach Name oder Alias aus.

Beispiel:

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

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

Als Antwort gibt der Server zurück:

• den absoluten Pfad des Projekts;

• den erkannten Stack;

• den aktuellen Git-Zweig;

• den Status des Working Tree;

• eine Liste der verfügbaren lokalen CLI-Tools.

projects.current

Gibt das aktuelle aktive Projekt und dessen Status zurück.

fs.list

Zeigt den Inhalt von Verzeichnissen innerhalb des aktiven Projekts an.

fs.read

Liest UTF-8-Dateien.

Das Lesen eines Zeilenbereichs wird unterstützt.

fs.write

Erstellt eine neue Datei oder überschreibt eine vorhandene vollständig.

fs.replace

Führt einen exakten Textersatz in der Datei durch.

Das Ersetzen einer oder aller Übereinstimmungen wird unterstützt.

fs.move

Verschiebt oder benennt eine Datei oder ein Verzeichnis innerhalb des aktiven Projekts um.

fs.delete

Löscht eine Datei oder ein Verzeichnis innerhalb des aktiven Projekts.

Das Löschen des Stammverzeichnisses des aktiven Projekts über dieses Tool ist verboten.

shell.run

Führt einen PowerShell-Befehl mit dem Arbeitsverzeichnis des aktiven Projekts aus.

Beispiele:

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

Separate Tools wie docker.*, git.* oder artisan.* werden in der aktuellen Version nicht implementiert.

Die universelle Schnittstelle zur Befehlsausführung ist die lokale Shell.

Docker

Docker ist ein optionales Tool.

Wenn Docker Desktop installiert ist, kann der KI-Client die Docker-CLI über shell.run verwenden.

Zum Beispiel:

docker compose ps

oder:

docker compose exec app npm test

Wenn Docker nicht vorhanden ist, funktioniert der MCP-Server für die übrigen Tools uneingeschränkt weiter.

Gleiches gilt für PHP, Composer, Python, GitHub CLI und andere Laufzeitumgebungen.

Git und GitHub

Git-Operationen werden über die lokal installierte Git-CLI ausgeführt.

Zum Beispiel:

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

Bei installierter und autorisierter GitHub-CLI sind Operationen über gh verfügbar:

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

Local Dev MCP speichert keine GitHub-Tokens und verwendet die vorhandene lokale Autorisierung.

Sicherheitsmodell

Datei-MCP-Tools sind auf das aktive Projekt beschränkt.

Versuche, über einen Pfad außerhalb des Workspace auf eine Datei zuzugreifen, werden blockiert.

Zum Beispiel:

..\..\some-file.txt

sollte es fs.read, fs.write oder anderen Datei-Tools nicht erlauben, das ausgewählte Projekt zu verlassen.

Allerdings ist shell.run keine Sandbox.

Der Befehl wird aus dem Verzeichnis des aktiven Projekts ausgeführt:

cwd = active project

aber PowerShell selbst kann technisch auf andere Verzeichnisse und lokale Ressourcen zugreifen, wenn dies direkt im Befehl angegeben ist.

Daher ist die aktuelle Version für eine vertrauenswürdige lokale Entwicklungsumgebung ausgelegt:

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

Status des aktiven Projekts

Das ausgewählte Projekt wird im Speicher des MCP-Prozesses gespeichert.

Nach einem Neustart des Servers muss das Projekt erneut ausgewählt werden.

Die aktuelle Version ist nicht für die gleichzeitige Arbeit mehrerer unabhängiger Benutzer über eine Serverinstanz ausgelegt.

Projektstruktur

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

Entwicklungsbefehle

Abhängigkeiten installieren:

npm install

Starten:

npm run dev

Typprüfung:

npm run check

Build:

npm run build

Gestartete Version ausführen:

npm start

Smoke-Test:

npm run smoke

Einschränkungen der aktuellen Version

In der aktuellen Version fehlen:

• Weboberfläche;

• Benutzersystem;

• Datenbank;

• ACL für einzelne Shell-Befehle;

• Bestätigung potenziell gefährlicher Befehle auf Serverebene;

• Docker-Container für den MCP selbst;

• separate Laufzeitprofile;

• Speichern des aktiven Projekts nach einem Neustart;

• öffentlicher Remote-Endpunkt;

• Mehrbenutzermodus.

Diese Funktionen können bei Bedarf hinzugefügt werden.

Diagnose

Node.js nicht gefunden

Überprüfen Sie:

node --version
npm --version

Node.js 20 oder neuer ist erforderlich.

MCP läuft, aber der Client verbindet sich nicht

Überprüfen Sie zuerst:

http://127.0.0.1:7676/health

Wenn /health nicht erreichbar ist, liegt das Problem auf der Seite des lokalen MCP.

Wenn /health funktioniert, überprüfen Sie den MCP-Endpunkt:

http://127.0.0.1:7676/mcp

und die Konfiguration des verwendeten MCP-Tunnels.

Port 7676 ist belegt

Ändern Sie den Port in config.local.json:

{
  "port": 7677
}

Verwenden Sie danach den neuen Port im MCP-Client.

Projekt wird nicht erkannt

Überprüfen Sie:

1. ob sich das Projekt in einem der roots befindet;

2. ob das Verzeichnis einen unterstützten Projekt-Marker enthält;

3. ob der Wert von scanDepth ausreicht;

4. fügen Sie das Projekt bei Bedarf explizit über projects hinzu.

Technologien

• TypeScript;

• Node.js;

• Model Context Protocol;

• offizielles MCP TypeScript SDK.

Dokumentation:

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