Molayo

© 2026 Molayo

GitHub요약2026. 05. 26. 20:38

answerlink/MCP-Workspace-Server

요약

MCP-Workspace-Server는 단일 MCP 서버를 통해 파일 조작, 코드 실행, 웹 배포, 데이터 처리 등 통합된 AI 에이전트 환경을 제공합니다. 여러 도구를 개별적으로 설정할 필요 없이 하나의 워크스페이스에서 엔터프라이즈급 개발 기능을 수행할 수 있습니다.

핵심 포인트

  • 단일 MCP 서버로 파일 조작부터 웹 배포까지 통합 관리
  • Python 및 Node.js 샌드박스 기반의 안전한 코드 실행 지원
  • 원클릭 웹 애플리케이션 배포 및 와일드카드 도메인 지원
  • Excel 데이터 처리 및 다양한 이미지 생성 기능 포함
  • 멀티 테넌트 격리 및 샌드박스를 통한 엔터프라이즈급 보안

English | 中文

🚀 단 하나의 MCP만으로 당신의 완전한 Agent 능력을 구현하세요!

파일 시스템을 넘어선 AI 개발 환경 - AI가 Claude Code처럼 완전한 웹 개발, 데이터 처리 및 코드 실행을 수행할 수 있도록 합니다.

💡

핵심 가치: 여러 개의 MCP 도구를 통합할 필요 없이, 하나의 MCP 서버만으로 파일 조작, 코드 실행, 웹 배포, 데이터 처리, 이미지 생성 등 완전한 Agent 능력을 제공합니다. 즉시 사용 가능한 원스톱 솔루션입니다.

강력한 MCP (Model Context Protocol) 서버로, 안전한 파일 시스템 조작을 제공할 뿐만 아니라 완전한 AI 개발 워크스페이스 (Workspace) 역할을 합니다. 코드 실행, 웹 애플리케이션 원클릭 배포, 와일드카드 도메인 접속, Excel 처리, 이미지 생성 등 엔터프라이즈급 기능을 지원합니다.

전통적인 방식: 완전한 기능을 구현하기 위해 여러 개의 MCP 도구를 통합해야 함

  • ❌ 파일 조작 → 별도의 MCP 필요
  • ❌ 코드 실행 → 또 다른 MCP 필요
  • ❌ 웹 배포 → 세 번째 MCP 필요
  • ❌ 데이터 처리 → 네 번째 MCP 필요
  • ❌ 이미지 생성 → 다섯 번째 MCP 필요
    결과: 설정이 복잡하고, 유지보수가 어려우며, 기능이 분산됨

우리의 방식: 단 하나의 MCP만으로 모든 기능을 즉시 사용 가능

  • ✅ 파일 조작 + 코드 실행 + 웹 배포 + 데이터 처리 + 이미지 생성
  • ✅ 통합 설정: 한 번의 설정으로 모든 기능 활성화
  • ✅ 통합 관리: 하나의 서비스로 집중 관리
  • ✅ 통합 보안: 하나의 보안 정책으로 전면 보호

우리는 전통적인 파일 시스템 서버를 훨씬 뛰어넘는 완전한 AI 개발 워크스페이스를 제공합니다:

  • 🚀 웹 개발 능력: AI가 완전한 웹 애플리케이션 (HTML/CSS/JS)을 생성하고 프로덕션 환경에 원클릭으로 배포할 수 있습니다. - 🌐
  • 와일드카드 도메인 배포: *.your-domain.com 형식을 지원합니다. 각 세션은 자동으로 독립적인 서브도메인을 할당받아 접속할 수 있습니다. - 💻
  • 코드 실행: Python 3.12 및 Node.js 20 샌드박스 (Sandbox) 환경이 내장되어 있어, 코드의 실시간 실행 및 디버깅을 지원합니다. - 📊
  • 데이터 처리: 템플릿, 수식, 포맷팅을 지원하는 완전한 Excel/CSV 처리 능력을 갖추고 있습니다. - 🎨
  • 이미지 생성: Mermaid 플로우차트, 데이터 차트, HTML 렌더링 등 다양한 방식의 이미지 생성을 지원합니다. - 🔍
  • 지능형 검색: 파일 내용 검색, 지식 베이스 검색, 웹 크롤링 등 고급 기능을 제공합니다. - 🔐
  • 엔터프라이즈급 보안: 멀티 테넌트 (Multi-tenant) 격리, 경로 보안 방어, 리소스 제한, 샌드박스 실행을 지원합니다.
전통적인 방식우리의 방식
5개 이상의 MCP 도구 필요단 1개의 MCP 필요
...
한 줄 요약: 하나의 MCP 서버 = 완전한 Agent 능력 스택 🚀

시나리오 1: AI 기반 웹 개발

AI가 완전한 프론트엔드 애플리케이션 생성 → 원클릭 배포 → 독립 도메인으로 접속
예시: https://user123_chat456.your-domain.com

시나리오 2: 데이터 분석 및 시각화

Excel 읽기 → 데이터 처리 → 차트 생성 → 보고서 작성 → 전시 페이지 배포

시나리오 3: 코드 개발 및 테스트

Python 스크립트 작성 → 테스트 실행 → 버그 수정 → API 서비스 배포

각 사용자/세션은 완전히 격리된 독립적인 가상 워크스페이스를 가집니다.

작업 디렉토리 명명 규칙:

X-User-IDX-Chat-ID작업 디렉토리
user123chat456user_data/user123_chat456/
user123(공백)user_data/user123/
(공백)chat456user_data/chat456/
(공백)(공백)기본 글로벌 모드 사용

HTTP 헤더를 통해 신원 식별자를 전달합니다:

X-User-ID: 사용자 고유 식별자 (선택 사항)
X-Chat-ID: 세션 고유 식별자 (선택 사항)

LLM 관점의 완전 가상화: AI 모델은 /를 루트 디렉토리로 하는 깨끗한 가상 파일 시스템을 보게 됩니다.

LLM이 보는 경로 | 실제 물리 경로
─────────────────────────────────────────────────────────
/ | /server/user_data/user123_chat456/
...

장점:

  • ✅ 서버의 실제 디렉토리 구조를 노출하지 않음
  • ✅ AI 플랫폼이 물리적 경로 정보를 알 수 없음
  • ✅ AI의 파일 조작 명령을 단순화함
  • ✅ 보안성 및 개인정보 보호 향상

경로 탐색 공격 (Path Traversal Attack)을 방지하기 위해 다층 보안 메커니즘이 내장되어 있습니다:

공격 시도          결과
─────────────────────────────────────────────────
/../../../etc/passwd ❌ 차단됨
...

보안 메커니즘:

경로 해석 (Path Resolution): Path.resolve()를 사용하여 모든 .. 및 심볼릭 링크 (Symbolic Link)를 해석합니다.
경계 검사 (Boundary Check): 해석된 경로가 허용된 범위 내에 있는지 검증합니다.
이중 보호 (Double Protection): 경로가 해석되더라도 반드시 allowed_dirs 내에 있어야 합니다.

다양한 AI 플랫폼에 적합하도록 Server-Sent Events (SSE) 전송을 지원합니다:

클라이언트          서버
│                   │
│──── GET /sse ──────────────────────▶│ SSE 연결 수립
...

Web 애플리케이션 원클릭 배포:

  • AI가 생성한 프론트엔드 프로젝트는 preview_frontend 도구를 통해 원클릭으로 배포할 수 있습니다. - 접근 가능한 URL을 자동으로 생성하며 HTTPS를 지원합니다.
  • 사용자 정의 엔트리 파일(Entry File) 및 디렉토리 구조를 지원합니다.

와일드카드 도메인 배포 (운영 환경):

{
"preview": {
"wildcard_domain": "*.proxy.your-domain.com",
...

설정 후, 각 세션은 자동으로 독립적인 서브도메인을 부여받습니다:

user123_chat456.proxy.your-domain.com

user789_chat012.proxy.your-domain.com

장점:

  • ✅ 도메인 및 포트를 수동으로 설정할 필요 없음
  • ✅ 자동 격리로 상호 간섭 없음
  • ✅ HTTPS 지원, 운영 환경 준비 완료 (Production-ready)
  • ✅ 단일 포트 서비스로 배포 간소화
도구기능특징
fs_writeWeb 파일 생성 (HTML/CSS/JS)형식을 자동 인식하며, 전체 프론트엔드 프로젝트 지원
preview_frontend정적 프론트엔드 원클릭 배포와일드카드 도메인 지원, 독립 서브도메인 자동 생성
execPython/Node.js 코드 실행샌드박스 (Sandbox) 환경, 실시간 디버깅 지원
generate_image차트 및 플로우차트 생성Mermaid, 데이터 시각화, HTML 렌더링
도구기능
fs_read파일 읽기 (일괄 처리, Excel, 행 범위 지원)
fs_write파일 생성/덮어쓰기 (형식 자동 인식)
fs_ops파일 시스템 작업 (list/mkdir/move/info/delete)
fs_replaceSEARCH/REPLACE 기반의 정밀한 파일 편집
fs_search파일 검색 (glob=파일명 기준, content=내용 기준 정규식)
도구기능
fs_readExcel 파일 읽기 (sheet, range 파라미터 지원)
fs_writeExcel 파일 생성/덮어쓰기 (형식 자동 인식)
excel_editExcel 편집 (셀 일괄 업데이트, 포맷팅)
list_excel_templates사용 가능한 Excel 템플릿 목록 표시
create_excel_from_template템플릿으로부터 Excel 파일 생성
도구기능설정 항목
kb_search기업 지식 베이스 (Knowledge Base) glob 검색kb.enabled=true
kb_read지식 베이스 파일 읽기 (Markdown 반환)kb.enabled=true
crawl_url웹 페이지 크롤링 및 Markdown 반환web_crawl.enabled=true
web_search웹 검색web_search.enabled=true

우리는 강력한 All-in-One MCP Server입니다. 단 한 번의 설정으로 귀하의 AI 플랫폼에 완전한 에이전트 (Agent) 능력을 제공합니다:

  • ✅ 파일 작업: 파일 읽기/쓰기, 검색, 편집
  • ✅ 코드 실행: Python/Node.js 샌드박스 환경
  • ✅ Web 배포: 프론트엔드 애플리케이션 원클릭 배포, 와일드카드 도메인 지원
  • ✅ 데이터 처리: Excel/CSV 완전 처리 능력
  • ✅ 이미지 생성: Mermaid 플로우차트, 데이터 차트
  • ✅ 지능형 검색: 지식 베이스 검색, 웹 크롤링 (선택 사항)

여러 개의 MCP 도구를 통합할 필요 없이, 하나의 MCP Server로 모든 요구 사항을 충족할 수 있습니다!

주요 AI 플랫폼과 완벽하게 통합되며, 설정이 간편하고 즉시 사용 가능합니다:

  • Dify 워크플로우(Workflow) 설정 진입

  • MCP Tool 노드 추가 - SSE 전송 프로토콜 선택

  • 추가

  • MCP Server 연결 구성
    SSE 주소: http://your-server:8000/sse

  • 요청 헤더 설정 (멀티테넌시 격리)
    X-User-ID: {{user_id}} X-Chat-ID: {{conversation_id}}

  • 완료! 이제 당신의 Dify Agent는 완전한 파일 조작, 코드 실행, 웹 배포 등의 능력을 갖추게 됩니다.

  • FastGPT 지식베이스/애플리케이션 설정 진입

  • 외부 도구 (External Tool) → MCP 추가 - 전송 방식에서 SSE 선택

  • 추가

  • 연결 정보 구성
    MCP Server URL: http://your-server:8000/sse

  • 사용자 식별 구성 (선택 사항, 멀티테넌시 격리용)
    사용자 정의 헤더 (Custom Header): X-User-ID: {{userId}} X-Chat-ID: {{chatId}}

  • 도구 활성화: 모든 도구가 자동으로 사용 가능해지며, 개별적으로 구성할 필요가 없습니다!

  • Cherry Studio 설정 진입

  • MCP Servers 설정 열기 - 새로운 MCP Server 추가

  • 열기

  • 연결 구성
    { "name": "MCP Workspace Server", "transport": "sse", "url": "http://your-server:8000/sse" }

  • 세션 식별 설정 (멀티테넌시 지원)

  • Cherry Studio가 사용자 및 세션 정보를 자동으로 전달합니다.

  • 각 세션은 독립적인 워크스페이스를 할당받습니다.

기존 방식우리의 All-in-One MCP 사용 시
5개 이상의 서로 다른 MCP 도구를 구성해야 함단 1개의 MCP Server만 구성하면 됨
...

구성이 완료되면, 당신의 AI Agent는 즉시 다음 능력을 갖게 됩니다:

  • 📝 파일 조작: 파일 생성, 읽기, 편집, 검색
  • 💻 코드 실행: Python/Node.js 스크립트 실행 및 실시간 디버깅
  • 🌐 웹 개발: 프론트엔드 애플리케이션 생성 및 원클릭 프로덕션 환경 배포
  • 📊 데이터 처리: Excel 읽기 및 편집, 보고서 생성
  • 🎨 이미지 생성: 플로우차트, 데이터 시각화 차트 생성
  • 🔍 지능형 검색: 파일 내용 검색, 지식베이스 검색 (활성화 시)

하나의 MCP Server = 완전한 Agent 능력 스택 🚀

# 프로젝트 클론
git clone <repository-url>
cd mcp-filesystem
...

💡 이미지는 실행 환경을 포함하며, 코드는 볼륨(volume)을 통해 마운트됩니다. 코드를 업데이트하려면 다음 명령만 실행하면 됩니다:

git pull && docker-compose restart

⚠️ 중요 안내: 본 프로젝트의 실행 환경은 Docker 베이스 이미지에 크게 의존합니다. 여기에는 완전한 Python 3.12, Node.js 20 실행 환경 및 모든 시스템 의존성(Tesseract OCR, 이미지 처리 라이브러리 등)이 포함되어 있습니다. Docker 방식으로 배포하는 것을 강력히 권장하며, 로컬에서 Python을 직접 실행하는 것은 권장하지 않습니다. 로컬 개발이 필요한 경우 모든 시스템 의존성이 설치되어 있는지 확인하십시오.

📖

상세 통합 안내: 상단의 🔌 AI 플랫폼 통합 섹션을 참조하십시오. Dify, FastGPT, Cherry Studio의 전체 구성 단계가 포함되어 있습니다.

빠른 연결 정보:

SSE 주소:http://your-server:8000/sse

요청 헤더 (멀티테넌시 격리):
X-User-ID : {{userId}} 또는 고정 사용자 ID
X-Chat-ID : {{chatId}} 또는 고정 세션 ID

Claude Desktop (STDIO 모드):

설정 파일 편집:

  • macOS:
    ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows:
    %APPDATA%/Claude/claude_desktop_config.json

{
"mcpServers": {
"mcp-workspace": {
...

┌─────────────────────────────────────────────────────────────┐
│ AI 플랫폼 (Dify / FastGPT / Cherry Studio) │
└─────────────────────────────────────────────────────────────┘
...

모니터링, 디버깅 및 운영 관리를 위한 HTTP 인터페이스를 제공합니다.

Admin API는 Bearer Token 인증이 필요합니다. 먼저 config.json을 설정하십시오:

# 예시 설정 파일 복사
cp config.example.json config.json
# 설정을 편집하여 관리자 키(admin key)를 설정합니다
...

{
"admin_token": "your-secret-admin-token-here"
}

모든 Admin API 요청은 반드시 Authorization 헤더를 포함해야 합니다:

curl -H "Authorization: Bearer your-secret-admin-token-here" \

⚠️ 보안 주의: config.json은 .gitignore에 추가되어 있으므로, 버전 관리 시스템(repository)에 커밋하지 마십시오.

GET /admin/stats
Authorization: Bearer <admin_token>

응답 예시:

{
"success": true,
"user_data_dir": "/path/to/user_data",
...

GET /admin/workspaces
GET /admin/workspaces?user_id=user123
Authorization: Bearer <admin_token>

GET /admin/workspace/{workspace_id}
GET /admin/workspace/{workspace_id}/tree?max_depth=5
Authorization: Bearer <admin_token>

DELETE /admin/workspace/{workspace_id}?confirm=yes
Authorization: Bearer <admin_token>

경고: 이 작업은 되돌릴 수 없습니다! 삭제를 실행하려면 반드시 ?confirm=yes 파라미터를 추가해야 합니다.

사용자에게 관리자 토큰 없이 워크스페이스 디렉토리 트리 조회를 제공합니다.

GET /api/workspace/tree?user_id={user_id}&chat_id={chat_id}&max_depth=5

  • Authorization 헤더가 필요하지 않습니다. - 해당 user_id + chat_id 조합에 대응하는 워크스페이스만 반환합니다. - 각 디렉토리 계층은 최근 수정 시간 순으로 정렬되며, 대역폭 절약을 위해 상위 20개의 파일/폴더만 유지하고 나머지는 필터링됩니다.

config.json / config.example.json에 최대 파일 크기, 기본 읽기 행 수, 지원 형식 및 수식 감지 스위치 설정을 위한 excel 섹션이 추가되었습니다. - 템플릿: excel.templates_file은 기본적으로 excel_templates/templates.json을 가리킵니다. 템플릿 소스 파일은 excel_templates/에 위치하며, 외부에는 title/desc만 노출됩니다. create_excel_from_template은 이름 중복을 자동으로 피합니다. 처음 사용할 때는 templates_example.json을 복사하여 templates.json을 생성하고, 실제 상황에 맞춰 템플릿 경로를 구성하십시오. - 환경 변수 덮어쓰기: MCP_EXCEL_MAX_ROWS, MCP_EXCEL_MAX_SIZE_MB. - 상세 파라미터 및 예시는 docs/EXCEL_TOOLS.md를 참조하십시오.

config.json에 mcp 섹션이 추가되어 transport (기본값 sse), host (기본값 0.0.0.0), port (기본값 18089)를 설정할 수 있습니다. - CLI 파라미터 --transport/--host/--port는 설정 파일보다 우선순위가 높습니다. - Web 관리 인터페이스: config.json에 admin_web 섹션이 추가되었습니다 (enabled 기본값 false, password 기본값 123456). 활성화 후 http://<host>:<port>/admin에 접속하여 비밀번호를 입력하면 user_data 아래의 파일 트리를 확인하고 텍스트/Markdown/CSV를 미리 볼 수 있습니다.

단계 1: 프론트엔드 프로젝트 생성

Tool: fs_write
Arguments: {
"path": "/index.html",
...

단계 2: 원클릭 배포

Tool: preview_frontend
Arguments: {
"entry_file": "index.html"
...

결과 반환:

{
"success": true,
"url": "https://user123_chat456.proxy.your-domain.com/index.html",
...

단계 3: 배포된 애플리케이션 접속

  • 독립적인 서브도메인 자동 획득
  • HTTPS 지원 (설정 시)
  • 포트 및 도메인의 수동 설정 불필요
Tool: fs_read
Arguments: {
"path": "/file.txt",
...

Tool: fs_read
Arguments: {
"path": ["/file1.txt", "/file2.json", "/data.xlsx"]
...

Tool: fs_search
Arguments: {
"search_type": "content", # glob=파일명 기준, content=내용 기준
...

Tool: fs_replace
Arguments: {
"path": "/config.py",
...

Tool: exec
Arguments: {
"code": "print('Hello, World!')"
...

Tool: exec
Arguments: {
"file": "/script.py",
...

Tool: fs_read
Arguments: {
"path": "/data.xlsx",
...

Tool: fs_write
Arguments: {
"path": "/output.xlsx",
...

Tool: excel_edit
Arguments: {
"path": "/data.xlsx",
...

Tool: generate_image
Arguments: {
"mermaid_code": "flowchart TD\nA[시작] --> B[처리] --> C[종료]"
...

또는 HTML을 사용하여 복잡한 차트를 렌더링할 수 있습니다:

Tool: generate_image
Arguments: {
"html_code": "<html><body><h1>데이터 시각화</h1>...</body></html>"
...

운영 환경 배포

  • 리버스 프록시 (Nginx)를 사용하여 HTTPS 처리

  • 접속 IP를 제한하거나 API 키 인증 사용

  • 합리적인 요청 빈도 제한 (Rate Limiting) 설정

데이터 격리

  • X-User-ID 및 X-Chat-ID가 신뢰할 수 있는 소스에서 생성되도록 보장

  • 만료된 세션 작업 디렉토리를 정기적으로 정리

Admin API 보호

  • location /admin/ { allow 10.0.0.0/8; deny all; proxy_pass http://localhost:8000; }를 통해 보장
변수명설명기본값
MCP_WORKSPACES_DIR사용자 작업 공간 루트 디렉토리프로젝트 디렉토리/user_data
MCP_ALLOWED_DIRS접근 허용 디렉토리 목록 (글로벌 패턴)현재 작업 디렉토리
FASTMCP_PORT서버 포트8000

Issue와 Pull Request 제출을 환영합니다!

AI 자동 생성 콘텐츠

본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0