mcplocal

로컬 파일 MCP 서버로, MCP 지원 클라이언트(가능한 경우 ChatGPT Web 사용자 지정 MCP 앱 포함)가 명시적으로 구성된 하나의 디렉터리 내에서 파일을 읽고, 검색하고, 수정할 수 있게 해줍니다.

기능

• 레거시 HTTP+SSE: GET /sse + POST /messages

• 최신 MCP HTTP 엔드포인트: /mcp

• 상태 확인: /health

• 샌드박스: 모든 파일 경로는 MCP_ROOT 아래에서 확인됩니다

• 선택적 Bearer 인증

• 프로젝트 탐색을 위한 읽기/검색 도구

• 코딩 워크플로를 위한 쓰기/편집 도구

• 삭제는 기본적으로 비활성화

• 셸/CLI 실행 도구 없음

• 외부 데이터베이스에 대한 의존성 없음

• Node.js 20+

MCP TypeScript SDK는 현재 원격 서버에 Streamable HTTP를 권장하며 HTTP+SSE를 하위 호환성 전송 방식으로 취급합니다. 이 프로젝트는 의도적으로 두 가지를 모두 노출하여, 구형 SSE 클라이언트도 계속 연결할 수 있고 최신 클라이언트는 /mcp를 사용할 수 있게 합니다.

Related MCP server: FilesystemMCP

1. 실행

cp .env.example .env
# edit MCP_ROOT if needed
npm start

예시:

MCP_ROOT=~/Projects
MCP_HOST=127.0.0.1
MCP_PORT=8008
MCP_AUTH_TOKEN=change-me

그런 다음:

SSE:        http://127.0.0.1:8008/sse
Streamable: http://127.0.0.1:8008/mcp
Health:     http://127.0.0.1:8008/health

2. ChatGPT Web이 연결할 수 있는 대상

ChatGPT Web은 호스팅 서비스에서 localhost에 직접 연결할 수 없습니다. 로컬 MCP 서버는 지원되는 Secure MCP Tunnel/프라이빗 네트워크 메커니즘을 통해 연결 가능하게 만들어야 합니다. 원격 MCP 엔드포인트를 확보한 후 ChatGPT Developer Mode에서 사용자 지정 MCP 앱으로 추가하고, 도구를 스캔한 다음 활성화하세요.

로컬 서비스를 매핑하는 터널의 경우 로컬 오리진은 다음과 같습니다:

http://127.0.0.1:8008/sse

또는 최신 클라이언트의 경우:

http://127.0.0.1:8008/mcp

인증과 명시적인 네트워크 정책 없이 이 서버를 공개 인터넷에 노출하지 마세요.

3. ChatGPT에 노출되는 도구

• list_files(path, recursive)

• read_file(path, startLine, endLine)

• write_file(path, content, createDirs)

• edit_file(path, oldText, newText, replaceAll)

• search_files(query, path, regex, caseSensitive, maxResults)

• create_directory(path)

• file_info(path)

• delete_file(path) — MCP_ENABLE_DELETE=true일 때만

일반적인 코딩 워크플로:

1. list_files로 프로젝트를 파악합니다.

2. search_files로 심볼을 찾습니다.

3. read_file로 관련 코드를 검토합니다.

4. edit_file로 정밀한 변경을 하거나, write_file로 새 파일을 만듭니다.

5. read_file로 결과를 다시 확인합니다.

4. 보안 모델

MCP_ROOT가 경계입니다. ../ 경로 탐색과 그 밖의 절대 경로는 거부됩니다. 바이너리/읽기 불가 파일은 검색에서 건너뜁니다. 파일 크기는 MCP_MAX_FILE_BYTES로 제한됩니다.

이 서버는 의도적으로 임의의 셸 실행을 노출하지 않습니다. 즉, ChatGPT는 코드를 편집할 수 있지만 이 MCP를 통해 rm, curl, 패키지 매니저, git 명령 또는 임의의 프로그램을 자동으로 실행할 수 없습니다.

개발 머신의 경우 MCP_HOST=127.0.0.1을 유지하고 서버를 모든 인터페이스에 바인딩하는 대신 지원되는 Secure MCP Tunnel을 사용하세요.

5. 빌드

npm run build
node dist/server.js

빌드는 의존성이 없으며 런타임을 dist/에 복사합니다.

6. Docker

docker build -t mcplocal .
docker run --rm -p 8008:8008 -v "$PWD:/workspace" mcplocal

7. ChatGPT에서의 예시 프롬프트

Inspect this local project and tell me where the authentication flow is implemented. Do not modify anything.

Open src/server.js and refactor the error handling. Before changing it, read the relevant code. Then edit only the necessary section and show me what changed.

Search the project for TODO comments and create a report at reports/todos.md.

라이선스

MIT