本地DeepWiki MCP服务器

一个本地的、以隐私为中心的MCP服务器，为具有基于RAG的问答功能的私有存储库生成DeepWiki风格的文档。

快速入门

立即尝试 --包含此项目的预构建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

为您自己的回购建立索引 --需要法学硕士提供者（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 下面）和LLM提供者：

开放人工智能 （默认）--设置 OPENAI_API_KEY 环境变量
Anthropic --set ANTHROPIC_API_KEY 环境变量
奥拉玛 （完全本地，需要GPU）--安装Ollama，然后 ollama pull qwen3-coder:30b

特性

多语言代码解析 使用树形图（Python、Types/JavaScript、Go、Rust、Java、C/C++、Objective-C、Swift、Ruby、PHP、Kotlin、C#）
基于AST的分块 尊重代码结构（函数、类、方法）
语义搜索 使用LanceDB矢量数据库
LLM驱动的维基生成 支持Ollama（本地）、Anthropic和OpenAI
可配置的嵌入 -本地（句子转换）或OpenAI
增量索引 -仅重新处理更改的文件
基于RAG的问答 -询问有关代码库的问题
建筑健康 -9维评分（复杂性、耦合性、气味、层次、流失、内聚性、重复性、可测试性、可维护性）
深度研究模式 -复杂建筑问题的多步推理
网页用户界面 -在浏览器中浏览生成的wiki
导出为HTML -生成用于共享的静态HTML网站
导出为PDF -使用美人鱼图生成可打印的PDF文档
交互式代码映射 -使用Mermaid图实现跨文件执行流可视化
延迟页面生成 -访问时按需生成的维基页面缺失

安装

使用紫外线（推荐）

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

配置

运行init向导以自动生成配置文件：

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

紫外线是一个快速的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/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的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}"
      }
    }
  }
}

帆板运动

添加 ~/.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代码（副本）

添加 .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客户端）

服务器通过stdio使用 MCP协议.启动方式：

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

或无紫外线（之后 pip install -e .):

local-deepwiki

注：替换 /path/to/local-deepwiki-mcp 使用克隆存储库的实际路径。添加 ANTHROPIC_API_KEY 到 env 如果使用Anthropic而不是OpenAI，则阻止。

MCP工具（64个工具）

服务器暴露 64个MCP工具 横跨8个类别。下面是最常用的工具和示例，然后是完整的工具参考。

核心工具

`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导出为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`	通过树保姆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`	层违规检测（处理程序→服务→核心）
`get_churn_metrics`	文件更改频率与流失×复杂性复合
`get_co_change`	通过Jaccard相似性实现共变耦合
`get_cohesion_metrics`	LCOM4类内聚和模块导入内聚
`get_duplication_metrics`	1型（精确）和2型（结构）克隆检测
`get_testability_metrics`	测试代码比、覆盖映射、断言密度
`get_maintainability_metrics`	每个功能的可维护性指数（霍尔斯特德+CC+LOC）
`get_recommendations`	优先考虑具有努力/影响的重构建议
`compare_architecture`	比较两个git ref之间的健康状况
`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
登录（或创建帐户）
点击 创建新密钥
复制密钥并将其设置在您的环境中：

export OPENAI_API_KEY="sk-..."

要持久化它，请将导出添加到您的 ~/.zshrc 或 ~/.bashrc.

Anthropic

首选 console.anthropic.com/settings/keys
点击 创建密钥
在您的环境中设置它：

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 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

美人鱼图可选： npm install -g @mermaid-js/mermaid-cli

故障排除

Ollama连接错误

如果您看到“连接到Ollama失败”：

确保Olama正在运行： ollama serve
验证模型是否已拉取： ollama list
检查默认URL是否有效： curl http://localhost:11434/api/tags
如果使用自定义端口，请更新 config.yaml 与正确 base_url

PDF导出失败

“未找到pango”或类似的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

美人鱼图未在PDF中呈现：

安装mermaid cli： npm install -g @mermaid-js/mermaid-cli
通过以下方式进行验证： mmdc --version
没有mermaidcli，图表显示为代码块

大型存储库的内存问题

对于包含100k+行代码的存储库：

如果您有更多的RAM，请在配置中增加批处理大小限制
使用 full_rebuild: false 用于初始索引后的增量更新
考虑通过以下方式排除大型生成文件 exclude_patterns 在配置中

LLM质量问题

如果维基内容有幻觉或质量低：

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

Web UI未加载

检查端口8080是否正在使用中： lsof -i :8080
尝试其他端口： deepwiki serve .deepwiki --port 8081
确保 .deepwiki 目录存在并包含生成的wiki

示例配置

这 examples/ 目录包含示例配置文件：

config-local.yaml -使用Ollama和句子转换器进行完全本地设置
config-cloud.yaml -使用Anthropic/OpenAI进行基于云的设置
config-hybrid.yaml -使用云LLM进行本地嵌入
roles.yaml -RBAC角色配置示例

发展

# Install dev dependencies
uv sync --extra dev

# Run tests
pytest

# Run the server directly
uv run local-deepwiki

建筑

┌─────────────────────────────────────────────────────────────────────┐
│                      MCP Server (Python/FastMCP)                    │
├─────────────────────────────────────────────────────────────────────┤
│  43 tools across 8 categories:                                      │
│  Core (8) · Generators (12) · Analysis & Search (10) · Codemap (2) │
│  Research & Progress (4) · Agentic (5) · Web Server (2)            │
└─────────────────────────────────────────────────────────────────────┘
           │                    │                    │
           ▼                    ▼                    ▼
┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│   Tree-sitter    │  │     LanceDB      │  │   LLM Provider   │
│  (Code Parsing)  │  │  (Vector Store)  │  │ (Doc Generation) │
└──────────────────┘  └──────────────────┘  └──────────────────┘
           │                    │                    │
           ▼                    ▼                    ▼
┌──────────────────────────────────────────────────────────────────┐
│                     Flask Web UI                                  │
│  Wiki Browser · Chat (RAG Q&A) · Codemap Explorer · Search      │
└──────────────────────────────────────────────────────────────────┘

许可证

麻省理工学院

Local DeepWiki MCP Server

快速接入

详细介绍