Local Dev MCP

Local MCP server for an AI agent working with multiple projects on a single Windows machine.

Local Dev MCP provides the AI client with access to local projects, the file system, and command execution via PowerShell. A single server instance can work with several repositories located in one or more root directories.

Docker is not a mandatory dependency. Projects can use Docker, Node.js, PHP, Python, or any other locally installed stack.

Installation

1. Install Node.js

Local Dev MCP requires Node.js version 20 or newer.

Check the current version:

node --version
npm --version

If Node.js is not installed, install the current LTS version from the official Node.js website.

After installation, close and reopen PowerShell or Windows Terminal.

2. Get Local Dev MCP

Clone the repository:

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

Or download the repository archive and unpack it to a convenient directory, for example:

C:\Tools\local-dev-mcp

3. Perform initial setup

Run:

FIRST_RUN.cmd

The script automatically:

• checks for Node.js;

• prompts for the root directory with local projects;

• creates config.local.json;

• installs npm dependencies;

• checks TypeScript;

• starts the MCP server.

For example, if the employee's projects are located here:

C:\Users\User\Documents\GitHub

you need to specify this directory on first run.

Another employee may have any path:

D:\Projects

or:

C:\Development

The configuration is stored locally and does not go into Git.

4. Verify startup

After a successful start, open:

http://127.0.0.1:7676/health

Expected response:

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

MCP endpoint:

http://127.0.0.1:7676/mcp

5. Connect the MCP client

In the local MCP tunnel being used, specify:

http://127.0.0.1:7676/mcp

After connecting, the AI client will get access to the registered MCP tools.

6. Check the MCP interface

With the server running, run:

SMOKE_TEST.cmd

or:

npm run smoke

The test should successfully connect to the MCP endpoint and return a list of available tools.

Related MCP server: Windows-MCP

Subsequent launches

After the first installation, no reconfiguration is required.

To start the server, use:

START.cmd

or:

npm run dev

Local configuration is saved in:

config.local.json

To change the projects directory, you can edit this file manually or rerun the initial setup.

Features

• automatic project discovery in one or more root directories;

• selection of the active project by name or alias;

• file operations inside the selected project;

• execution of PowerShell commands with the working directory of the selected project;

• basic detection of the used stack;

• checking availability of local CLI tools;

• working with Git and GitHub CLI through the local shell;

• Streamable HTTP MCP endpoint;

• local health-check endpoint;

• protection of file MCP operations from going outside the active project.

Automatic detection of the following technologies and tools is supported:

• Git;

• Node.js;

• PHP / Composer;

• Laravel;

• Docker / Docker Compose;

• Python;

• Go;

• Rust.

Architecture

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

The server does not implement separate MCP tools for each framework or runtime.

Commands like:

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

are executed through the universal shell.run tool.

Due to this, the MCP server does not depend on the technology stack of a specific project.

Requirements

Mandatory:

• Windows 10 or Windows 11;

• Node.js 20 or newer;

• at least one local directory with projects.

Additional tools are installed only when needed:

• Git;

• GitHub CLI;

• Docker Desktop;

• PHP;

• Composer;

• Python;

• other CLI and runtimes used by projects.

Docker is not required for Local Dev MCP to work.

First launch

1. Clone or unpack the project

For example:

C:\Tools\local-dev-mcp

2. Run initial setup

FIRST_RUN.cmd

The script:

1. checks for Node.js;

2. prompts for the path to the projects directory;

3. creates a local configuration file;

4. installs npm dependencies;

5. runs a TypeScript check;

6. starts the MCP server.

By default, the following path is suggested:

%USERPROFILE%\Documents\GitHub

If necessary, you can specify another one:

D:\Projects

3. Verify startup

Open:

http://127.0.0.1:7676/health

Expected response:

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

MCP endpoint:

http://127.0.0.1:7676/mcp

By default, the server listens only on 127.0.0.1 and is not directly published to the local network or the internet.

4. Connect the MCP client

In the local MCP tunnel or another compatible client, specify:

http://127.0.0.1:7676/mcp

5. Run a smoke test

With the server running:

SMOKE_TEST.cmd

or:

npm run smoke

The test checks the connection to MCP and outputs the list of registered tools.

Regular launch

After initial setup:

START.cmd

or:

npm run dev

Configuration

Local configuration is stored in:

config.local.json

The file is excluded from Git via .gitignore and is intended for settings of a specific workstation.

Example:

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

Multiple root directories

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

Each directory is scanned independently.

Scan depth

If the project structure is nested:

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

you can increase:

{
  "scanDepth": 2
}

The maximum value in the current version is 5.

Explicit project addition and alias

Projects can be added manually:

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

After that, the project can be selected both by its main name and by alias.

Project discovery

A directory is considered a project if it contains at least one of the supported markers:

.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

After a directory is identified as a project, scanning of its internal folders stops.

This allows not identifying internal dependencies and service directories as separate workspaces.

MCP tools

projects.list

Returns a list of discovered and explicitly configured projects.

projects.select

Selects the active project by name or alias.

Example:

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

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

In response, the server returns:

• the absolute path of the project;

• the detected stack;

• the current Git branch;

• the working tree state;

• the list of available local CLI tools.

projects.current

Returns the current active project and its state.

fs.list

Outputs the contents of directories inside the active project.

fs.read

Reads UTF-8 files.

Reading a range of lines is supported.

fs.write

Creates a new file or completely overwrites an existing one.

fs.replace

Performs an exact text replacement in a file.

Replacement of one or all matches is supported.

fs.move

Moves or renames a file or directory inside the active project.

fs.delete

Deletes a file or directory inside the active project.

Deleting the root directory of the active project through this tool is prohibited.

shell.run

Executes a PowerShell command with the working directory of the active project.

Examples:

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 docker.*, git.*, or artisan.* tools are not implemented in the current version.

The universal command execution interface is the local shell.

Docker

Docker is an optional tool.

If Docker Desktop is installed, the AI client can use the Docker CLI through shell.run.

For example:

docker compose ps

or:

docker compose exec app npm test

If Docker is absent, the MCP server continues to work without restrictions for the other tools.

The same applies to PHP, Composer, Python, GitHub CLI, and other runtimes.

Git and GitHub

Git operations are performed through the locally installed Git CLI.

For example:

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

With GitHub CLI installed and authorized, operations via gh are available:

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

Local Dev MCP does not store GitHub tokens and uses the existing local authorization.

Security model

File MCP tools are limited to the active project.

Attempts to access a file through a path that goes beyond the workspace are blocked.

For example:

..\..\some-file.txt

should not allow fs.read, fs.write, or other file tools to go beyond the selected project.

At the same time, shell.run is not a sandbox.

The command is executed from the active project directory:

cwd = active project

but PowerShell itself can technically access other directories and local resources if this is specified directly in the command.

Therefore, the current version is designed for a trusted local development environment:

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

Active project state

The selected project is stored in the memory of the MCP process.

After restarting the server, the project must be selected again.

The current version is not designed for simultaneous work of multiple independent users through one server instance.

Project structure

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

Development commands

Installing dependencies:

npm install

Running:

npm run dev

Type check:

npm run check

Build:

npm run build

Running the built version:

npm start

Smoke test:

npm run smoke

Limitations of the current version

The current version lacks:

• web interface;

• user system;

• database;

• ACL for individual shell commands;

• confirmation of potentially dangerous commands at the server level;

• Docker container for MCP itself;

• separate runtime profiles;

• saving the active project after restart;

• public remote endpoint;

• multi-user mode.

These features may be added as needed.

Diagnostics

Node.js not found

Check:

node --version
npm --version

Node.js 20 or newer is required.

MCP is running, but the client does not connect

First check:

http://127.0.0.1:7676/health

If /health is unavailable, the problem is on the local MCP side.

If /health works, check the MCP endpoint:

http://127.0.0.1:7676/mcp

and the configuration of the MCP tunnel being used.

Port 7676 is busy

Change the port in config.local.json:

{
  "port": 7677
}

After that, use the new port in the MCP client.

Project is not detected

Check:

1. whether the project is inside one of the roots;

2. whether the directory contains a supported project marker;

3. whether the scanDepth value is sufficient;

4. if necessary, add the project explicitly via projects.

Technologies

• TypeScript;

• Node.js;

• Model Context Protocol;

• official MCP TypeScript SDK.

Documentation:

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