Local Dev MCP

단일 Windows 머신에서 AI 에이전트가 여러 프로젝트를 작업할 수 있게 하는 로컬 MCP 서버입니다.

Local Dev MCP는 AI 클라이언트에게 로컬 프로젝트, 파일 시스템, PowerShell을 통한 명령 실행에 대한 액세스를 제공합니다. 서버 인스턴스 하나로 하나 또는 여러 루트 디렉터리에 있는 여러 리포지토리를 동시에 처리할 수 있습니다.

Docker는 필수 종속성이 아닙니다. 프로젝트는 Docker, Node.js, PHP, Python 또는 로컬에 설치된 다른 어떤 스택이든 사용할 수 있습니다.

설치

1. Node.js 설치

Local Dev MCP를 실행하려면 Node.js 버전 20 이상이 필요합니다.

현재 버전을 확인하세요:

node --version
npm --version

Node.js가 설치되어 있지 않으면 Node.js 공식 웹사이트에서 최신 LTS 버전을 설치하세요.

설치 후 PowerShell 또는 Windows Terminal을 닫았다가 다시 여세요.

2. Local Dev MCP 받기

리포지토리를 클론하세요:

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

또는 리포지토리 아카이브를 다운로드하여 원하는 디렉터리에 압축을 풀면 됩니다. 예:

C:\Tools\local-dev-mcp

3. 초기 설정 실행

다음을 실행하세요:

FIRST_RUN.cmd

스크립트는 자동으로 다음 작업을 수행합니다:

• Node.js 설치 여부를 확인합니다;

• 로컬 프로젝트가 있는 루트 디렉터리를 요청합니다;

• config.local.json을 생성합니다;

• npm 종속성을 설치합니다;

• TypeScript를 검사합니다;

• MCP 서버를 시작합니다.

예를 들어 직원의 프로젝트가 다음 위치에 있다면:

C:\Users\User\Documents\GitHub

첫 실행 시 이 디렉터리를 지정해야 합니다.

다른 직원의 경우 경로는 다를 수 있습니다:

D:\Projects

또는:

C:\Development

설정은 로컬에 저장되며 Git에 포함되지 않습니다.

4. 실행 확인

실행에 성공하면 다음을 여세요:

http://127.0.0.1:7676/health

예상 응답:

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

MCP 엔드포인트:

http://127.0.0.1:7676/mcp

5. MCP 클라이언트 연결

사용 중인 로컬 MCP 터널에 다음을 지정하세요:

http://127.0.0.1:7676/mcp

연결 후 AI 클라이언트는 등록된 MCP 도구에 액세스할 수 있습니다.

6. MCP 인터페이스 확인

서버가 실행 중인 상태에서 다음을 실행하세요:

SMOKE_TEST.cmd

또는:

npm run smoke

테스트는 MCP 엔드포인트에 성공적으로 연결되어 사용 가능한 도구 목록을 반환해야 합니다.

Related MCP server: Windows-MCP

이후 실행

최초 설치 후에는 재설정이 필요 없습니다.

서버를 실행하려면 다음을 사용하세요:

START.cmd

또는:

npm run dev

로컬 구성은 다음 위치에 저장됩니다:

config.local.json

프로젝트 디렉터리를 변경하려면 이 파일을 수동으로 편집하거나 초기 설정을 다시 실행하면 됩니다.

기능

• 하나 또는 여러 루트 디렉터리에서 프로젝트 자동 검색;

• 이름 또는 별칭(alias)으로 활성 프로젝트 선택;

• 선택한 프로젝트 내 파일 작업;

• 선택한 프로젝트를 작업 디렉터리로 사용하는 PowerShell 명령 실행;

• 사용 중인 스택의 기본 감지;

• 로컬 CLI 도구 사용 가능 여부 확인;

• 로컬 셸을 통한 Git 및 GitHub CLI 작업;

• Streamable HTTP MCP 엔드포인트;

• 로컬 health-check 엔드포인트;

• 파일 MCP 작업이 활성 프로젝트 범위를 벗어나지 않도록 보호.

다음 기술 및 도구의 자동 감지가 지원됩니다:

• Git;

• Node.js;

• PHP / Composer;

• Laravel;

• Docker / Docker Compose;

• Python;

• Go;

• Rust.

아키텍처

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

서버는 각 프레임워크 또는 런타임별로 별도의 MCP 도구를 구현하지 않습니다.

다음과 같은 형태의 명령은:

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

범용 도구인 shell.run을 통해 실행됩니다.

이로 인해 MCP 서버는 특정 프로젝트의 기술 스택에 의존하지 않습니다.

요구 사항

필수:

• Windows 10 또는 Windows 11;

• Node.js 20 이상;

• 프로젝트가 있는 로컬 디렉터리 1개 이상.

추가 도구는 필요한 경우에만 설치됩니다:

• Git;

• GitHub CLI;

• Docker Desktop;

• PHP;

• Composer;

• Python;

• 프로젝트에서 사용하는 기타 CLI 및 런타임.

Local Dev MCP 실행에는 Docker가 필요하지 않습니다.

첫 실행

1. 프로젝트 클론 또는 압축 해제

예:

C:\Tools\local-dev-mcp

2. 초기 설정 실행

FIRST_RUN.cmd

스크립트는 다음을 수행합니다:

1. Node.js 설치 여부를 확인합니다;

2. 프로젝트 디렉터리 경로를 요청합니다;

3. 로컬 구성 파일을 생성합니다;

4. npm 종속성을 설치합니다;

5. TypeScript 검사를 수행합니다;

6. MCP 서버를 시작합니다.

기본적으로 다음 경로가 제안됩니다:

%USERPROFILE%\Documents\GitHub

필요하면 다른 경로를 지정할 수 있습니다:

D:\Projects

3. 실행 확인

다음을 여세요:

http://127.0.0.1:7676/health

예상 응답:

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

MCP 엔드포인트:

http://127.0.0.1:7676/mcp

기본적으로 서버는 127.0.0.1에서만 수신 대기하며 로컬 네트워크나 인터넷에 직접 공개되지 않습니다.

4. MCP 클라이언트 연결

로컬 MCP 터널 또는 다른 호환 클라이언트에 다음을 지정하세요:

http://127.0.0.1:7676/mcp

5. 스모크 테스트 실행

서버가 실행 중인 상태에서:

SMOKE_TEST.cmd

또는:

npm run smoke

테스트는 MCP 연결을 확인하고 등록된 도구 목록을 출력합니다.

일반 실행

초기 설정 후:

START.cmd

또는:

npm run dev

구성

로컬 구성은 다음 위치에 저장됩니다:

config.local.json

이 파일은 .gitignore를 통해 Git에서 제외되며 특정 워크스테이션 설정을 위한 것입니다.

예:

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

여러 루트 디렉터리

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

각 디렉터리는 독립적으로 스캔됩니다.

스캔 깊이

프로젝트 구조가 중첩된 경우:

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

다음 값을 늘릴 수 있습니다:

{
  "scanDepth": 2
}

현재 버전의 최대값은 5입니다.

프로젝트 및 별칭(alias) 명시적 추가

프로젝트는 수동으로 추가할 수 있습니다:

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

그 후에는 기본 이름과 별칭(alias) 중 원하는 방식으로 프로젝트를 선택할 수 있습니다.

프로젝트 검색

디렉터리에 지원되는 마커(marker)가 하나 이상 포함되어 있으면 해당 디렉터리는 프로젝트로 간주됩니다:

.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

디렉터리가 프로젝트로 확인되면 내부 폴더에 대한 스캔이 중단됩니다.

이를 통해 내부 종속성과 서비스 디렉터리가 별도의 워크스페이스로 식별되지 않습니다.

MCP 도구

projects.list

검색된 프로젝트와 명시적으로 구성된 프로젝트 목록을 반환합니다.

projects.select

이름 또는 별칭(alias)으로 활성 프로젝트를 선택합니다.

예:

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

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

서버는 응답으로 다음을 반환합니다:

• 프로젝트의 절대 경로;

• 감지된 스택;

• 현재 Git 브랜치;

• 작업 트리(working tree) 상태;

• 사용 가능한 로컬 CLI 도구 목록.

projects.current

현재 활성 프로젝트와 해당 상태를 반환합니다.

fs.list

활성 프로젝트 내 디렉터리의 내용을 출력합니다.

fs.read

UTF-8 파일을 읽습니다.

줄 범위 읽기가 지원됩니다.

fs.write

새 파일을 생성하거나 기존 파일을 완전히 덮어씁니다.

fs.replace

파일에서 텍스트를 정확히 교체합니다.

하나 또는 모든 일치 항목에 대한 교체가 지원됩니다.

fs.move

활성 프로젝트 내에서 파일 또는 디렉터리를 이동하거나 이름을 변경합니다.

fs.delete

활성 프로젝트 내에서 파일 또는 디렉터리를 삭제합니다.

이 도구를 통한 활성 프로젝트 루트 디렉터리 삭제는 금지됩니다.

shell.run

활성 프로젝트를 작업 디렉터리로 사용하여 PowerShell 명령을 실행합니다.

예:

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

현재 버전에서는 별도의 docker.*, git.* 또는 artisan.* 도구가 구현되지 않습니다.

명령 실행의 범용 인터페이스는 로컬 셸입니다.

Docker

Docker는 선택적 도구입니다.

Docker Desktop이 설치되어 있으면 AI 클라이언트는 shell.run을 통해 Docker CLI를 사용할 수 있습니다.

예:

docker compose ps

또는:

docker compose exec app npm test

Docker가 없어도 MCP 서버는 나머지 도구에 대해 제한 없이 계속 작동합니다.

PHP, Composer, Python, GitHub CLI 및 기타 런타임에도 동일하게 적용됩니다.

Git 및 GitHub

Git 작업은 로컬에 설치된 Git CLI를 통해 수행됩니다.

예:

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

GitHub CLI가 설치되고 인증되어 있으면 gh를 통한 작업을 사용할 수 있습니다:

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

Local Dev MCP는 GitHub 토큰을 저장하지 않으며 기존 로컬 인증을 사용합니다.

보안 모델

파일 MCP 도구는 활성 프로젝트로 제한됩니다.

워크스페이스 범위를 벗어나는 경로를 통한 파일 접근 시도는 차단됩니다.

예:

..\..\some-file.txt

는 fs.read, fs.write 또는 다른 파일 도구가 선택한 프로젝트 범위를 벗어나는 것을 허용하지 않아야 합니다.

단, shell.run은 샌드박스가 아닙니다.

명령은 활성 프로젝트 디렉터리에서 실행됩니다:

cwd = active project

그러나 PowerShell 자체는 명령에 직접 지정된 경우 기술적으로 다른 디렉터리와 로컬 리소스에 접근할 수 있습니다.

따라서 현재 버전은 신뢰할 수 있는 로컬 개발 환경을 전제로 합니다:

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

활성 프로젝트 상태

선택한 프로젝트는 MCP 프로세스 메모리에 저장됩니다.

서버를 다시 시작한 후에는 프로젝트를 다시 선택해야 합니다.

현재 버전은 하나의 서버 인스턴스를 통해 여러 독립 사용자가 동시에 작업하는 시나리오를 지원하지 않습니다.

프로젝트 구조

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

개발 명령

종속성 설치:

npm install

실행:

npm run dev

타입 검사:

npm run check

빌드:

npm run build

빌드된 버전 실행:

npm start

스모크 테스트:

npm run smoke

현재 버전의 제한 사항

현재 버전에는 다음 기능이 없습니다:

• 웹 인터페이스;

• 사용자 시스템;

• 데이터베이스;

• 개별 셸 명령에 대한 ACL;

• 서버 수준에서 잠재적으로 위험한 명령에 대한 확인;

• MCP 자체를 위한 Docker 컨테이너;

• 별도의 런타임 프로필;

• 재시작 후 활성 프로젝트 유지;

• 공개 원격 엔드포인트;

• 다중 사용자 모드.

이러한 기능은 필요에 따라 추가될 수 있습니다.

진단

Node.js를 찾을 수 없음

다음을 확인하세요:

node --version
npm --version

Node.js 20 이상이 필요합니다.

MCP가 실행 중이지만 클라이언트가 연결되지 않음

먼저 다음을 확인하세요:

http://127.0.0.1:7676/health

/health에 접근할 수 없으면 문제는 로컬 MCP 쪽에 있습니다.

/health가 작동하면 MCP 엔드포인트를 확인하세요:

http://127.0.0.1:7676/mcp

그리고 사용 중인 MCP 터널의 구성을 확인하세요.

포트 7676이 사용 중

config.local.json에서 포트를 변경하세요:

{
  "port": 7677
}

그런 다음 MCP 클라이언트에서 새 포트를 사용하세요.

프로젝트가 검색되지 않음

다음을 확인하세요:

1. 프로젝트가 roots 중 하나 안에 있는지;

2. 디렉터리에 지원되는 프로젝트 마커가 포함되어 있는지;

3. scanDepth 값이 충분한지;

4. 필요한 경우 projects를 통해 프로젝트를 명시적으로 추가하세요.

기술

• TypeScript;

• Node.js;

• Model Context Protocol;

• 공식 MCP TypeScript SDK.

문서:

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