Servidor MCP Local DeepWiki

Un servidor MCP local centrado en la privacidad que genera documentación al estilo DeepWiki para repositorios privados con capacidades de preguntas y respuestas basadas en RAG.

Inicio rápido

Pruébelo inmediatamente — se incluye una wiki preconstruida de este proyecto:

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

Indexe su propio repositorio — requiere un proveedor de LLM (OpenAI, Anthropic u 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

Requisitos: Python 3.11+, uv (consulte Instalación de uv a continuación) y un proveedor de LLM:

• OpenAI (predeterminado) — establezca la variable de entorno OPENAI_API_KEY

• Anthropic — establezca la variable de entorno ANTHROPIC_API_KEY

• Ollama (totalmente local, requiere GPU) — instale Ollama, luego ollama pull qwen3-coder:30b

Características

• Análisis de código multilingüe usando tree-sitter (Python, TypeScript/JavaScript, Go, Rust, Java, C/C++, Objective-C, Swift, Ruby, PHP, Kotlin, C#)

• Fragmentación basada en AST que respeta la estructura del código (funciones, clases, métodos)

• Búsqueda semántica usando la base de datos vectorial LanceDB

• Generación de wiki impulsada por LLM con soporte para Ollama (local), Anthropic y OpenAI

• Embeddings configurables - locales (sentence-transformers) u OpenAI

• Indexación incremental - solo reprocesa los archivos modificados

• Preguntas y respuestas basadas en RAG - haga preguntas sobre su código base

• Salud de la arquitectura - puntuación de 9 dimensiones (complejidad, acoplamiento, olores, capas, rotación, cohesión, duplicación, capacidad de prueba, mantenibilidad)

• Modo de investigación profunda - razonamiento de varios pasos para preguntas arquitectónicas complejas

• Interfaz web - explore la wiki generada en su navegador

• Exportación a HTML - genere un sitio HTML estático para compartir

• Exportación a PDF - genere documentación PDF imprimible con diagramas mermaid

• Mapa de código interactivo - visualización del flujo de ejecución entre archivos con diagramas Mermaid

• Generación de páginas bajo demanda - las páginas wiki faltantes se generan cuando se visitan

Instalación

Usando uv (recomendado)

cd local-deepwiki-mcp
uv sync

Todos los proveedores de LLM y la interfaz web se incluyen de forma predeterminada. Extra opcional para exportación a PDF:

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

Usando pip

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

Configuración

Ejecute el asistente de inicio para generar un archivo de configuración automáticamente:

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

O cree uno manualmente en ~/.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"

Instalación de uv

uv es un gestor de paquetes de Python rápido. Si no lo tiene:

# 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

Después de instalarlo, reinicie su terminal o ejecute source ~/.bashrc (o ~/.zshrc).

Integración del servidor MCP

El servidor MCP se ejecuta sobre stdio y funciona con cualquier herramienta de IA compatible con MCP. Inícielo manualmente con:

deepwiki mcp

O configure su herramienta de IA para iniciarlo automáticamente:

Claude Code

Añada a ~/.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

Añada a la configuración de MCP de Cursor (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

Añada a ~/.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)

Añada a .vscode/mcp.json en su espacio de trabajo:

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

Genérico (cualquier cliente MCP)

El servidor se comunica a través de stdio usando el protocolo MCP. Inicie con:

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

O sin uv (después de pip install -e .):

local-deepwiki

Nota: Reemplace /path/to/local-deepwiki-mcp con la ruta real donde clonó el repositorio. Añada ANTHROPIC_API_KEY al bloque env si usa Anthropic en lugar de OpenAI.

Herramientas MCP (64 herramientas)

El servidor expone 64 herramientas MCP en 8 categorías. A continuación se muestran las herramientas más utilizadas con ejemplos, seguidas de la referencia completa de herramientas.

Herramientas principales

index_repository

Indexa un repositorio y genera documentación wiki.

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

ask_question

Haga una pregunta sobre el código base usando RAG.

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

deep_research

Razonamiento de varios pasos para preguntas arquitectónicas complejas. Realiza descomposición de consultas, recuperación paralela, análisis de brechas y síntesis integral.

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

Herramientas de generación (12)

Herramientas de análisis y búsqueda (10)

Herramientas de salud de la arquitectura (17)

Herramientas de mapa de código (2)

Herramientas de investigación y progreso (4)

Herramientas de agente (5)

Herramientas de servidor web (2)

Comandos CLI

Todos los comandos son subcomandos de la CLI unificada deepwiki. Los puntos de entrada heredados (deepwiki-serve, deepwiki-export, etc.) siguen funcionando por compatibilidad con versiones anteriores.

# 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

Claves de API

OpenAI (predeterminado)

1. Vaya a platform.openai.com/api-keys

2. Inicie sesión (o cree una cuenta)

3. Haga clic en Create new secret key

4. Copie la clave y establézcala en su entorno:

export OPENAI_API_KEY="sk-..."

Para persistirla, añada el export a su ~/.zshrc o ~/.bashrc.

Anthropic

1. Vaya a console.anthropic.com/settings/keys

2. Haga clic en Create Key

3. Establézcala en su entorno:

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

Uso de un proxy compatible con OpenAI

Si su organización proporciona un punto final de API compatible con OpenAI (por ejemplo, a través de GitHub Copilot Enterprise o un proxy corporativo), establezca la base_url en su configuración:

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

La variable de entorno OPENAI_API_KEY sigue siendo necesaria para la autenticación.

Requisitos previos

Para soporte de LLM local:

• Ollama instalado y en ejecución

• Un modelo descargado (ej. ollama pull llama3.2)

Para exportación a PDF:

• Bibliotecas del sistema: pango, cairo, gdk-pixbuf (dependencias de WeasyPrint)

  • macOS: brew install pango

  • Ubuntu/Debian: apt install libpango-1.0-0 libpangocairo-1.0-0

• Opcional para diagramas mermaid: npm install -g @mermaid-js/mermaid-cli

Solución de problemas

Errores de conexión con Ollama

Si ve "Failed to connect to Ollama":

1. Asegúrese de que Ollama esté ejecutándose: ollama serve

2. Verifique que el modelo esté descargado: ollama list

3. Compruebe si la URL predeterminada funciona: curl http://localhost:11434/api/tags

4. Si usa un puerto personalizado, actualice config.yaml con la base_url correcta

Fallos en la exportación a PDF

"pango not found" o errores similares de 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