로컬 DeepWiki MCP 서버

RAG 기반 Q&A 기능을 갖춘 개인 저장소용 DeepWiki 스타일 문서를 생성하는 로컬, 개인정보 보호 중심의 MCP 서버입니다.

퀵스타트

즉시 체험하기 — 이 프로젝트의 미리 빌드된 위키가 포함되어 있습니다:

git clone https://github.com/UrbanDiver/local-deepwiki-mcp.git
cd local-deepwiki-mcp
uv sync                          # Install dependencies
deepwiki serve .deepwiki         # Browse the wiki at http://localhost:8080

자신의 저장소 인덱싱하기 — LLM 제공업체(OpenAI, Anthropic 또는 Ollama)가 필요합니다:

export OPENAI_API_KEY="..."      # Or ANTHROPIC_API_KEY for Anthropic
deepwiki init                    # Configure LLM + embedding providers
deepwiki config health-check     # Verify providers are working
deepwiki update /path/to/repo    # Index a repository and generate wiki
deepwiki serve /path/to/repo/.deepwiki

요구 사항: Python 3.11+, uv (uv 설치 참조), 그리고 LLM 제공업체:

OpenAI (기본값) — OPENAI_API_KEY 환경 변수 설정
Anthropic — ANTHROPIC_API_KEY 환경 변수 설정
Ollama (완전 로컬, GPU 필요) — Ollama 설치 후 ollama pull qwen3-coder:30b 실행

기능

다국어 코드 파싱 (tree-sitter 사용: Python, TypeScript/JavaScript, Go, Rust, Java, C/C++, Objective-C, Swift, Ruby, PHP, Kotlin, C#)
AST 기반 청킹 (코드 구조 준수: 함수, 클래스, 메서드)
의미론적 검색 (LanceDB 벡터 데이터베이스 사용)
LLM 기반 위키 생성 (Ollama(로컬), Anthropic, OpenAI 지원)
구성 가능한 임베딩 - 로컬(sentence-transformers) 또는 OpenAI
증분 인덱싱 - 변경된 파일만 재처리
RAG 기반 Q&A - 코드베이스에 대한 질문 가능
아키텍처 상태 - 9개 차원 점수 산정 (복잡도, 결합도, 코드 스멜, 계층, 변경률, 응집도, 중복, 테스트 용이성, 유지보수성)
Deep Research 모드 - 복잡한 아키텍처 질문을 위한 다단계 추론
웹 UI - 브라우저에서 생성된 위키 탐색
HTML 내보내기 - 공유를 위한 정적 HTML 사이트 생성
PDF 내보내기 - Mermaid 다이어그램이 포함된 인쇄 가능한 PDF 문서 생성
대화형 코드맵 - Mermaid 다이어그램을 통한 파일 간 실행 흐름 시각화
지연 페이지 생성 - 방문 시 필요한 위키 페이지를 요청에 따라 생성

설치

uv 사용 (권장)

cd local-deepwiki-mcp
uv sync

모든 LLM 제공업체와 웹 UI가 기본적으로 포함되어 있습니다. PDF 내보내기를 위한 선택적 추가 기능:

uv sync --extra pdf              # Add WeasyPrint for PDF export
uv sync --extra all              # Same as --extra pdf (all optional extras)

pip 사용

cd local-deepwiki-mcp
pip install -e ".[all]"          # Recommended: install with all extras
# or: pip install -e .           # Minimal: core only

구성

초기화 마법사를 실행하여 구성 파일을 자동으로 생성합니다:

deepwiki init                    # Interactive wizard
deepwiki init --non-interactive  # Auto-detect defaults (CI/CD)

또는 ~/.config/local-deepwiki/config.yaml에 수동으로 생성합니다:

embedding:
  provider: "local"  # or "openai"
  local:
    model: "all-MiniLM-L6-v2"
  openai:
    model: "text-embedding-3-small"

llm:
  provider: "openai"  # or "anthropic" or "ollama"
  openai:
    model: "gpt-4o"
    # base_url: "https://your-proxy.example.com/v1"  # For OpenAI-compatible proxies
  anthropic:
    model: "claude-sonnet-4-20250514"
  ollama:
    model: "qwen3-coder:30b"
    base_url: "http://localhost:11434"

parsing:
  languages:
    - python
    - typescript
    - javascript
    - go
    - rust
    - java
    - c
    - cpp
  max_file_size: 1048576
  exclude_patterns:
    - "node_modules/**"
    - "venv/**"
    - ".git/**"

chunking:
  max_chunk_tokens: 512
  overlap_tokens: 50

output:
  wiki_dir: ".deepwiki"
  vector_db_name: "vectors.lance"

uv 설치

uv는 빠른 Python 패키지 관리자입니다. 설치되어 있지 않다면:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip
pip install uv

# Or with Homebrew
brew install uv

설치 후 터미널을 다시 시작하거나 source ~/.bashrc (또는 ~/.zshrc)를 실행하세요.

MCP 서버 통합

MCP 서버는 stdio를 통해 실행되며 모든 MCP 호환 AI 도구와 작동합니다. 수동으로 시작하려면:

deepwiki mcp

또는 AI 도구가 자동으로 시작하도록 구성하세요:

Claude Code

~/.claude/claude_code_config.json에 추가:

{
  "mcpServers": {
    "local-deepwiki": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/local-deepwiki-mcp", "local-deepwiki"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

Cursor

Cursor의 MCP 설정에 추가 (Settings > MCP Servers > Add):

{
  "mcpServers": {
    "local-deepwiki": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/local-deepwiki-mcp", "local-deepwiki"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json에 추가:

{
  "mcpServers": {
    "local-deepwiki": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/local-deepwiki-mcp", "local-deepwiki"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

VS Code (Copilot)

워크스페이스의 .vscode/mcp.json에 추가:

{
  "servers": {
    "local-deepwiki": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/local-deepwiki-mcp", "local-deepwiki"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

Generic (모든 MCP 클라이언트)

서버는 MCP 프로토콜을 사용하여 stdio를 통해 통신합니다. 다음으로 실행:

uv run --directory /path/to/local-deepwiki-mcp local-deepwiki

또는 uv 없이 실행 (pip install -e . 이후):

local-deepwiki

참고: /path/to/local-deepwiki-mcp를 저장소를 복제한 실제 경로로 바꾸세요. OpenAI 대신 Anthropic을 사용하는 경우 env 블록에 ANTHROPIC_API_KEY를 추가하세요.

MCP 도구 (64개)

서버는 8개 카테고리에 걸쳐 64개의 MCP 도구를 제공합니다. 아래는 가장 자주 사용되는 도구와 예시이며, 그 뒤에 전체 도구 참조가 있습니다.

핵심 도구

`index_repository`

저장소를 인덱싱하고 위키 문서를 생성합니다.

{
  "repo_path": "/path/to/repo",
  "full_rebuild": false,
  "llm_provider": "ollama",
  "embedding_provider": "local"
}

`ask_question`

RAG를 사용하여 코드베이스에 대해 질문합니다.

{
  "repo_path": "/path/to/repo",
  "question": "How does the authentication system work?",
  "max_context": 5
}

`deep_research`

복잡한 아키텍처 질문을 위한 다단계 추론입니다. 쿼리 분해, 병렬 검색, 격차 분석 및 포괄적인 합성을 수행합니다.

{
  "repo_path": "/path/to/repo",
  "question": "How does the authentication system interact with the database layer?",
  "max_chunks": 30
}

도구	설명
`index_repository`	저장소 인덱싱 및 위키 문서 생성
`ask_question`	코드베이스에 대한 RAG 기반 Q&A
`deep_research`	쿼리 분해 및 합성을 통한 다단계 추론
`read_wiki_structure`	위키 목차 가져오기
`read_wiki_page`	특정 위키 페이지 읽기
`search_code`	코드베이스 전체 의미론적 검색
`export_wiki_html`	위키를 정적 HTML 사이트로 내보내기
`export_wiki_pdf`	Mermaid 다이어그램 렌더링과 함께 위키를 PDF로 내보내기

생성기 도구 (12개)

도구	설명
`get_diagrams`	Mermaid 다이어그램 생성 (클래스, 의존성, 모듈, 시퀀스)
`get_call_graph`	함수 호출 그래프 분석
`get_glossary`	검색 가능한 코드 엔티티 용어집
`get_inheritance`	클래스 계층 트리
`get_coverage`	문서 커버리지 분석
`get_changelog`	Git 기반 변경 로그 생성
`get_api_docs`	매개변수 및 반환 유형 추출
`get_test_examples`	엔티티에 대한 테스트 예제 추출
`detect_stale_docs`	오래된 위키 페이지 감지
`detect_secrets`	하드코딩된 자격 증명 스캔
`get_index_status`	저장소 인덱스 상태 및 상태 점검
`list_indexed_repos`	인덱싱된 모든 저장소 나열

분석 및 검색 도구 (10개)

도구	설명
`search_wiki`	위키 페이지 및 코드 엔티티 전체 텍스트 검색
`fuzzy_search`	Levenshtein 기반 이름 일치 ("의도하신 것이 이것인가요?")
`get_file_context`	소스 파일에 대한 임포트, 호출자 및 관련 파일
`explain_entity`	복합: 용어집 + 호출 그래프 + 상속 + 테스트 + API 문서
`impact_analysis`	역방향 호출 그래프 및 위험 수준을 포함한 영향 범위 분석
`get_complexity_metrics`	tree-sitter AST를 통한 순환 복잡도 및 중첩 깊이
`analyze_diff`	git diff를 영향받는 위키 페이지 및 엔티티에 매핑
`ask_about_diff`	코드 변경 사항에 대한 RAG 기반 Q&A
`get_project_manifest`	pyproject.toml, package.json 등에서 파싱된 메타데이터
`get_wiki_stats`	위키 상태 대시보드: 인덱스, 페이지, 커버리지, 상태

아키텍처 상태 도구 (17개)

도구	설명
`get_architecture_health`	9개 차원에 걸친 복합 상태 등급 (A-F)
`get_hotspots`	복잡도, 인지 복잡도, 매개변수, 길이 또는 중첩별 함수 순위
`get_coupling_metrics`	Robert C. Martin 결합도 지표 (Ca, Ce, I, A, D)
`get_design_smells`	God 클래스, 기능 욕심, 긴 메서드 등 감지
`get_layer_dependencies`	계층 위반 감지 (핸들러→서비스→코어)
`get_churn_metrics`	변경률×복잡도 복합 지표를 포함한 파일 변경 빈도
`get_co_change`	Jaccard 유사도를 통한 동시 변경 결합도
`get_cohesion_metrics`	LCOM4 클래스 응집도 및 모듈 임포트 응집도
`get_duplication_metrics`	유형 1(정확함) 및 유형 2(구조적) 복제 감지
`get_testability_metrics`	테스트 대 코드 비율, 커버리지 매핑, 단언 밀도
`get_maintainability_metrics`	함수별 유지보수성 지수 (Halstead + CC + LOC)
`get_recommendations`	노력/영향도별 우선순위가 지정된 리팩토링 제안
`compare_architecture`	두 git 참조 간 상태 비교
`get_architecture_trends`	과거 상태 점수 스냅샷
`get_module_health`	모듈 범위의 복잡도, 스멜, 결합도, 위험도
`get_onboarding_guide`	신규 개발자 온보딩 가이드
`get_guided_tour`	코드베이스 대화형 가이드 투어

코드맵 도구 (2개)

도구	설명
`generate_codemap`	Mermaid 다이어그램 및 LLM 서술을 포함한 파일 간 실행 흐름 맵
`suggest_codemap_topics`	호출 그래프 허브에서 흥미로운 진입점 발견

연구 및 진행 도구 (4개)

도구	설명
`list_research_checkpoints`	저장된 Deep Research 체크포인트 나열
`resume_research`	이전에 체크포인트된 연구 세션 재개
`cancel_research`	진행 중인 연구 작업 취소
`get_operation_progress`	장기 실행 작업의 진행 상황 확인

에이전트 도구 (5개)

도구	설명
`suggest_next_actions`	최근 작업에 기반하여 다음에 사용할 도구에 대한 상황 인식 제안
`run_workflow`	사전 정의된 다단계 워크플로우 실행 (예: 전체 분석, 빠른 검토)
`batch_explain_entities`	여러 엔티티에 대한 `explain_entity`의 배치 버전
`query_codebase`	에이전트 RAG: 청크 관련성 등급 지정, 더 나은 결과를 위해 쿼리 재작성
`find_tools`	자연어 쿼리에 기반하여 관련 도구 발견

웹 서버 도구 (2개)

도구	설명
`serve_wiki`	문서 탐색을 위한 위키 웹 서버 시작
`stop_wiki_server`	실행 중인 위키 웹 서버 중지

CLI 명령어

모든 명령어는 통합 deepwiki CLI의 하위 명령어입니다. 레거시 진입점 (deepwiki-serve, deepwiki-export 등)은 하위 호환성을 위해 여전히 작동합니다.

명령어	설명
`deepwiki init`	구성을 위한 대화형 설정 마법사
`deepwiki status`	인덱스 상태, 신선도 및 위키 커버리지 표시
`deepwiki update`	저장소 인덱싱 및 위키 재생성 (증분)
`deepwiki mcp`	MCP 서버 시작 (IDE 통합용)
`deepwiki serve`	웹 UI로 위키 서비스
`deepwiki watch`	감시 모드 - 파일 변경 시 자동 재인덱싱
`deepwiki export`	위키를 정적 HTML로 내보내기
`deepwiki export-pdf`	위키를 PDF로 내보내기
`deepwiki config`	구성 관리 (유효성 검사, 표시, 상태 점검, 프로필)
`deepwiki search`	대화형 퍼지 코드 검색
`deepwiki cache`	캐시 관리 (통계, 지우기, 정리)

# Setup
deepwiki init                                   # Interactive wizard
deepwiki init --non-interactive                  # Auto-detect defaults (CI/CD)
deepwiki init --non-interactive --force          # Overwrite existing config

# Indexing & status
deepwiki update                                  # Index repo and regenerate wiki
deepwiki update --full-rebuild                   # Force full rebuild
deepwiki update --dry-run                        # Preview what would change
deepwiki status                                  # Show index health dashboard
deepwiki status --json                           # Machine-readable output
deepwiki status --verbose                        # Detailed file-level info

# MCP server
deepwiki mcp                                     # Start MCP server (stdio)

# Web UI & export
deepwiki serve .deepwiki --port 8080             # Browse wiki in browser
deepwiki export .deepwiki --output ./html-export # Export to static HTML
deepwiki export-pdf .deepwiki -o docs.pdf        # Export to single PDF
deepwiki export-pdf .deepwiki --separate -o dir/ # Export each page as PDF

# Configuration
deepwiki config show                             # Show effective configuration
deepwiki config show --raw                       # Show raw YAML
deepwiki config validate                         # Check config for errors
deepwiki config health-check                     # Verify provider connectivity
deepwiki config profile list                     # List saved config profiles
deepwiki config profile save dev                 # Save current config as profile
deepwiki config profile use prod                 # Switch to a profile

# Utilities
deepwiki search                                  # Interactive fuzzy code search
deepwiki watch /path/to/repo                     # Auto-reindex on file changes
deepwiki cache stats                             # Show cache hit rates and sizes
deepwiki cache clear --llm --embedding           # Clear caches
deepwiki cache cleanup                           # Remove expired entries

API 키

OpenAI (기본값)

platform.openai.com/api-keys로 이동
로그인 (또는 계정 생성)
Create new secret key 클릭
키를 복사하여 환경에 설정:

export OPENAI_API_KEY="sk-..."

지속하려면 ~/.zshrc 또는 ~/.bashrc에 export를 추가하세요.

Anthropic

console.anthropic.com/settings/keys로 이동
Create Key 클릭
환경에 설정:

export ANTHROPIC_API_KEY="sk-ant-..."

OpenAI 호환 프록시 사용

조직에서 OpenAI 호환 API 엔드포인트를 제공하는 경우 (예: GitHub Copilot Enterprise 또는 기업용 프록시), 구성에서 base_url을 설정하세요:

llm:
  provider: "openai"
  openai:
    model: "gpt-4o"
    base_url: "https://your-proxy.example.com/v1"

OPENAI_API_KEY 환경 변수는 인증을 위해 여전히 필요합니다.

사전 요구 사항

로컬 LLM 지원:

Ollama 설치 및 실행 중
모델 풀링 완료 (예: ollama pull llama3.2)

PDF 내보내기:

시스템 라이브러리: pango, cairo, gdk-pixbuf (WeasyPrint 의존성)
- macOS: brew install pango
- Ubuntu/Debian: apt install libpango-1.0-0 libpangocairo-1.0-0
Mermaid 다이어그램 선택 사항: npm install -g @mermaid-js/mermaid-cli

문제 해결

Ollama 연결 오류

"Failed to connect to Ollama"가 표시되는 경우:

Ollama가 실행 중인지 확인: ollama serve
모델이 풀링되었는지 확인: ollama list
기본 URL이 작동하는지 확인: curl http://localhost:11434/api/tags
사용자 지정 포트를 사용하는 경우, 올바른 base_url로 config.yaml을 업데이트하세요.

PDF 내보내기 실패

"pango not found" 또는 유사한 Cairo/Pango 오류:

macOS: brew install pango cairo gdk-pixbuf
Ubuntu/Debian: `apt install libpango-1.0-0 libpangoc