Local DeepWiki MCP 服务器

一个本地、注重隐私的 MCP 服务器，可为私有仓库生成 DeepWiki 风格的文档，并具备基于 RAG 的问答能力。

快速入门

立即尝试 — 已包含此项目的预构建 wiki：

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 驱动的 wiki 生成：支持 Ollama（本地）、Anthropic 和 OpenAI
可配置的嵌入模型 - 本地（sentence-transformers）或 OpenAI
增量索引 - 仅重新处理已更改的文件
基于 RAG 的问答 - 针对您的代码库进行提问
架构健康度 - 9 维度评分（复杂度、耦合度、代码异味、分层、代码流失、内聚性、重复度、可测试性、可维护性）
深度研究模式 - 针对复杂架构问题的多步推理
Web UI - 在浏览器中浏览生成的 wiki
导出为 HTML - 生成静态 HTML 站点以供共享
导出为 PDF - 生成带有 mermaid 图表的打印级 PDF 文档
交互式代码地图 - 带有 Mermaid 图表的跨文件执行流可视化
懒加载页面生成 - 访问时按需生成缺失的 wiki 页面

安装

使用 uv（推荐）

cd local-deepwiki-mcp
uv sync

默认包含所有 LLM 提供商和 Web 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}"
      }
    }
  }
}

通用（任何 MCP 客户端）

服务器通过 MCP 协议使用 stdio 进行通信。启动命令：

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

或者在不使用 uv 的情况下（在 pip install -e . 之后）：

local-deepwiki

注意： 将 /path/to/local-deepwiki-mcp 替换为您克隆仓库的实际路径。如果使用 Anthropic 而非 OpenAI，请在 env 块中添加 ANTHROPIC_API_KEY。

MCP 工具（64 个工具）

服务器通过 8 个类别公开了 64 个 MCP 工具。以下是最常用的工具及其示例，随后是完整的工具参考。

核心工具

`index_repository`

索引仓库并生成 wiki 文档。

{
  "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`	索引仓库并生成 wiki 文档
`ask_question`	基于 RAG 的代码库问答
`deep_research`	带有查询分解和综合的多步推理
`read_wiki_structure`	获取 wiki 目录
`read_wiki_page`	读取特定的 wiki 页面
`search_code`	代码库语义搜索
`export_wiki_html`	将 wiki 导出为静态 HTML 站点
`export_wiki_pdf`	将 wiki 导出为带有 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`	检测过期的 wiki 页面
`detect_secrets`	扫描硬编码的凭据
`get_index_status`	仓库索引状态和健康度
`list_indexed_repos`	列出所有已索引的仓库

分析与搜索工具 (10)

工具	描述
`search_wiki`	跨 wiki 页面和代码实体的全文搜索
`fuzzy_search`	基于 Levenshtein 的名称匹配（“您是指？”）
`get_file_context`	源文件的导入、调用者和相关文件
`explain_entity`	复合工具：术语表 + 调用图 + 继承 + 测试 + API 文档
`impact_analysis`	带有反向调用图和风险等级的爆炸半径分析
`get_complexity_metrics`	通过 tree-sitter AST 获取圈复杂度和嵌套深度
`analyze_diff`	将 git diff 映射到受影响的 wiki 页面和实体
`ask_about_diff`	基于 RAG 的代码变更问答
`get_project_manifest`	从 pyproject.toml、package.json 等解析元数据
`get_wiki_stats`	Wiki 健康仪表板：索引、页面、覆盖率、状态

架构健康工具 (17)

工具	描述
`get_architecture_health`	9 个维度的复合健康评分 (A-F)
`get_hotspots`	按复杂度、认知复杂度、参数、长度或嵌套对函数进行排名
`get_coupling_metrics`	Robert C. Martin 耦合度指标 (Ca, Ce, I, A, D)
`get_design_smells`	检测上帝类、特性嫉妒、长方法等
`get_layer_dependencies`	分层违规检测 (handlers→services→core)
`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`	列出已保存的深度研究检查点
`resume_research`	恢复之前保存的研究会话
`cancel_research`	取消正在进行的研究操作
`get_operation_progress`	检查长时间运行操作的进度

智能体工具 (5)

工具	描述
`suggest_next_actions`	基于近期操作的上下文感知下一工具建议
`run_workflow`	运行预定义的多步工作流（例如：全面分析、快速审查）
`batch_explain_entities`	`explain_entity` 的批量版本，一次解释多个实体
`query_codebase`	智能体 RAG：评估分块相关性，重写查询以获得更好结果
`find_tools`	基于自然语言查询发现相关工具

Web 服务器工具 (2)

工具	描述
`serve_wiki`	启动 wiki Web 服务器以浏览文档
`stop_wiki_server`	停止正在运行的 wiki Web 服务器

CLI 命令

所有命令都是统一 deepwiki CLI 的子命令。旧版入口点（deepwiki-serve、deepwiki-export 等）仍可用于向后兼容。

命令	描述
`deepwiki init`	配置交互式设置向导
`deepwiki status`	显示索引健康度、新鲜度和 wiki 覆盖率
`deepwiki update`	索引仓库并重新生成 wiki（增量）
`deepwiki mcp`	启动 MCP 服务器（用于 IDE 集成）
`deepwiki serve`	使用 Web UI 提供 wiki 服务
`deepwiki watch`	监视模式 - 文件更改时自动重新索引
`deepwiki export`	将 wiki 导出为静态 HTML
`deepwiki export-pdf`	将 wiki 导出为 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-..."

要使其持久化，请将 export 添加到您的 ~/.zshrc 或 ~/.bashrc 中。

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 libpangocairo-1.0-0 libgdk-pixbuf2.0-0
Fedora: dnf install pango cairo gdk-pixbuf2

Mermaid 图表在 PDF 中未渲染：

安装 mermaid-cli: npm install -g @mermaid-js/mermaid-cli
验证：mmdc --version
如果没有 mermaid-cli，图表将显示为代码块

大型仓库的内存问题

对于代码行数超过 10 万行的仓库：

如果内存充足，请在配置中增加批处理大小限制
初始索引后，使用 full_rebuild: false 进行增量更新
考虑通过配置中的 exclude_patterns 排除大型生成文件

LLM 质量问题

如果 wiki 内容出现幻觉或质量低下：

从 Ollama 切换到 Anthropic 或 OpenAI 以获得更好的结果
尝试更大的本地模型（例如 qwen3-coder:30b 而非 llama3.2）
确保源文件已正确解析（检查支持的语言）

Web UI 无法加载

检查端口 8080 是否被占用：lsof -i :8080
尝试其他端口：deepwiki serve .deepwiki --port 8081
确保 .deepwiki 目录存在