deepseek-mcp

Un servidor MCP que permite a Claude Code delegar una unidad acotada de trabajo de repositorio a DeepSeek como subagente local.

Claude sigue siendo el orquestador: decide el alcance, la arquitectura y la corrección. DeepSeek es un trabajador de ejecución para la parte con mayor consumo de tokens — explorar el repositorio, hacer cambios rutinarios o repetitivos, y ejecutar las pruebas — dentro de un espacio de trabajo único autorizado y bajo presupuestos estrictos.

El objetivo es dejar de pagar dos veces por el mismo contexto. Si Claude lee un subsistema y luego DeepSeek lo lee de nuevo, no se ha ahorrado nada; por eso la decisión de delegación pertenece antes de las lecturas amplias.

User
 ↓
Claude: plan + define goal/scope
 ↓
DeepSeek: inspect repo + read code + implement + test
 ↓
DeepSeek: compact structured summary
 ↓
Claude: review diff/results + final answer

DeepSeek es el trabajador principal del repositorio; Claude es el orquestador. Claude planifica, toma las decisiones de arquitectura y seguridad, revisa el diff devuelto y escribe la respuesta final. DeepSeek hace el trabajo del repositorio: explorar, Glob/Grep/ Read, entender el código, implementar, probar y hacer arreglos rutinarios. Claude delega antes de leer archivos fuente de forma amplia, y DeepSeek descubre los archivos relevantes por sí mismo dentro del alcance autorizado y devuelve un resumen estructurado y compacto — Claude nunca envía contenidos de archivos.

Requiere Python 3.11+ y una clave de API de DeepSeek. Una única dependencia en tiempo de ejecución: el SDK de MCP. Todo lo demás es la biblioteca estándar. ripgrep se usa para la búsqueda cuando está presente y se usa un escaneo en Python puro cuando no lo está.

1. Instalar

El paquete aún no está publicado en PyPI, así que instálalo desde un checkout. Instálalo una vez, de forma global — no es una dependencia del proyecto, y funciona en todos los repositorios.

git clone https://github.com/giaminhgist/DeepSeek_MCP.git
cd DeepSeek_MCP

uv tool install .          # recommended: isolated, and puts deepseek-mcp on PATH
# or
pipx install .
# or, into the current environment
pip install .

Confirma que el script de consola se resuelve:

deepseek-mcp --version     # -> deepseek-mcp 0.1.0

Si el comando no se encuentra, el directorio de instalación no está en tu PATH. Con uv, ejecuta uv tool update-shell y abre una nueva shell.

deepseek-mcp sin argumentos inicia el servidor MCP en stdio. Eso es lo que Claude Code ejecuta; normalmente no lo invocarías tú mismo.

Related MCP server: claude-code

2. Establecer la clave de API

Obtén una clave en https://platform.deepseek.com/. Nunca la pongas en un repositorio de proyecto. Expórtala desde tu perfil de shell:

export DEEPSEEK_API_KEY="sk-your-key-here"     # ~/.bashrc, ~/.zshrc, …

# Windows PowerShell
setx DEEPSEEK_API_KEY "sk-your-key-here"

Luego verifica que el servidor puede verla:

deepseek-mcp --check       # prints a health report as JSON; exits 1 if unusable

--check imprime "mode": "enabled" y "status": "ok" cuando la clave es legible. La clave en sí nunca aparece en el informe.

Tres fuentes de clave admitidas, en orden de precedencia:

1. DEEPSEEK_MCP_API_KEY o DEEPSEEK_API_KEY en el entorno del servidor.

2. api_key_env en el archivo de configuración del usuario, que nombra una variable de entorno diferente para leer.

3. api_key en el archivo de configuración del usuario — aceptada, pero desaconsejada, y produce una advertencia al inicio, porque pone la clave en el disco.

Todo lo demás es opcional; consulta Referencia de configuración. La única otra variable que vale la pena conocer de antemano es DEEPSEEK_MCP_WORKSPACE, que fija la raíz del espacio de trabajo autorizado en lugar de descubrirla (consulta Espacio de trabajo).

3. Añadir el servidor a Claude Code

Si DEEPSEEK_API_KEY ya está exportada en el entorno que Claude Code hereda:

claude mcp add deepseek --scope user -- deepseek-mcp

Si no lo está — por ejemplo, en un lanzamiento de escritorio que no lee tu perfil de shell — pásala explícitamente:

claude mcp add deepseek --scope user -e DEEPSEEK_API_KEY=sk-your-key-here -- deepseek-mcp

--scope user lo registra para todos los proyectos. Usa --scope local para el proyecto actual solamente.

Configuración manuscrita equivalente:

{
  "mcpServers": {
    "deepseek": {
      "command": "deepseek-mcp",
      "env": {
        "DEEPSEEK_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Omite el bloque env por completo cuando la clave ya está en el entorno heredado. No confirmes una clave en ningún archivo del repositorio.

4. Verificar la conexión

claude mcp list            # deepseek should be listed and connected

Luego, dentro de Claude Code:

• ejecuta /mcp — deepseek debería aparecer con sus dos herramientas;

• pide a Claude que llame a deepseek_health. Un servidor que funciona responde con status: "ok", mode: "enabled", el model predeterminado y la lista de allowed_models, la raíz del espacio de trabajo resuelta, las capacidades habilitadas, los límites de presupuesto y un objeto usage con los totales acumulados del trabajador para este proceso de servidor.

Sin clave configurada, el servidor igualmente se inicia y responde a deepseek_health — informando status: "error", mode: "disabled" — de modo que el problema se puede diagnosticar desde dentro de Claude Code. No realiza ningún trabajo en ese estado.

5. Solución de problemas

Los registros van a stderr como registros event key=value, nunca a stdout. Aumenta el detalle con DEEPSEEK_MCP_LOG_LEVEL=DEBUG, o envíalos a un archivo con DEEPSEEK_MCP_LOG_FILE=/absolute/path.log.

La superficie de herramientas

Dos herramientas, deliberadamente.

deepseek_health

Configuración y salud: estado, el model predeterminado y la lista de allowed_models, la raíz del espacio de trabajo autorizado y cómo se resolvió, las capacidades habilitadas, los límites de presupuesto y un objeto usage con los totales acumulados del trabajador para este proceso de servidor. Sin secretos. Úsala para confirmar que el trabajador está disponible y para dimensionar una delegación antes de enviarla.

delegate_to_deepseek

Una unidad de trabajo acotada, como un contrato estructurado en lugar de un bloque de prosa:

{
  "objective": "Treat a None row as invalid and cover it with a test.",
  "scope": ["src/importer/**", "tests/importer/**"],
  "constraints": ["Do not change the public response schema."],
  "acceptance_criteria": ["validate_row(None) returns False."],
  "verification": [["pytest", "tests/importer", "-q"]],
  "mode": "write"
}

El trabajador entonces itera por su cuenta — glob, grep, read, edit, run, repair — y devuelve un resultado compacto, nunca una transcripción:

{
  "status": "completed",
  "summary": "Treated a None row as invalid and added a regression test.",
  "changed_files": ["src/importer/validate.py"],
  "created_files": ["tests/importer/test_none.py"],
  "deleted_files": [],
  "inspected_files": ["src/importer/__init__.py"],
  "verification": [
    {"argv": ["pytest", "tests/importer", "-q"], "exit_code": 0, "summary": "24 passed"}
  ],
  "warnings": [],
  "unresolved": [],
  "assumptions": [],
  "diff_stat": " src/importer/validate.py | 3 ++-",
  "metrics": {
    "turns": 7, "tool_calls": 12, "prompt_tokens": 18400,
    "completion_tokens": 2100, "duration_seconds": 41.2,
    "files_read": 4, "files_changed": 2, "compactions": 0
  },
  "session_usage": {
    "delegations": 3, "turns": 19, "tool_calls": 31,
    "prompt_tokens": 51200, "completion_tokens": 6400,
    "total_tokens": 57600, "since": "server start"
  },
  "model": "deepseek-chat",
  "analysis": {
    "important_files": ["src/importer/validate.py"],
    "architecture_notes": ["validate_row is the single entry point for row checks."],
    "dependencies": ["src/importer/schema.py"],
    "suggested_scope": ["src/importer/**", "tests/importer/**"],
    "risks": ["Changing the None handling may affect callers that rely on the old behaviour."]
  },
  "debug_ledger": ["R src/importer/validate.py", "E src/importer/validate.py", "X pytest tests/importer -q"]
}

model es el modelo que realmente ejecutó la delegación, después de la resolución de anulación por tarea. analysis está presente solo cuando la delegación lo solicitó, y lleva los cinco campos del mapa del repositorio. debug_ledger es el registro de ejecución compacto de una línea por llamada de herramienta, poblado solo cuando el servidor se ejecuta con debug habilitado. metrics informa el uso y la forma de tokens de esta delegación; session_usage lleva los totales acumulados del trabajador para este proceso de servidor, incluyendo esta delegación — delegations, turns, tool_calls, prompt_tokens, completion_tokens, total_tokens y since (siempre el literal "server start").

El contador que hay detrás de usage y session_usage está en memoria y limitado al proceso del servidor: se reinicia cuando el servidor MCP se reinicia, que es exactamente lo que registra el campo since. No se persiste en disco. Solo se cuentan las delegaciones que llegaron al worker: una solicitud rechazada antes (servidor deshabilitado, un campo de solicitud inválido o un modelo fuera de la lista permitida de allowed_models) nunca llamó a un modelo, por lo que no incrementa delegations ni ningún recuento de tokens. total_tokens se calcula a partir de sus partes en lugar de almacenarse, por lo que no puede desviarse.

Estados: completed, partial, blocked, failed, budget_exceeded, disabled. Los fallos esperados — config datos incorrectos, una ruta rechazada, un comando denegado, un presupuesto agotado, un error del proveedor — regresan siempre como uno de estos estados con un motivo. Un traceback de Python nunca lo hace.

Los resultados llevan conclusiones, nunca transcripciones crudas de Read/Grep/herramientas. El registro de depuración es el registro compacto — una línea por llamada a herramienta —, no la salida de las herramientas, incluso cuando la depuración está activada.

Los modos acotan, nunca amplían

Un modo se cruza con las capacidades configuradas del servidor. Una solicitud que pida más de lo que el servidor concede se rechaza antes de cualquier llamada a la API; no puede ampliar la política en ningún caso.

De lo que no se confía el worker

Dos cosas del resultado no vienen del modelo:

• La lista de archivos modificados proviene de observar las herramientas más una comparación con git status contra una instantánea tomada antes de la ejecución, de modo que las ediciones sin confirmar que el usuario tuviera antes nunca se notifican como trabajo del worker.

• El estado. Un completed reclamado desciende a partial si la verificación solicitada no se ejecutó nunca o si finalizó con un código distinto de cero. failed y budget_exceeded son veredictos del servidor y el worker no puede reclamarlos en absoluto.

Verifique de todos modos. git status --short, git diff --stat, y lea después los fragmentos modificados en proporción al riesgo. completed es una afirmación, no una prueba.

Presupuestos

Cada delegación está acotada y la ejecución se detiene con un motivo estructurado en lugar de sobrepasar los límites: turnos (24), llamadas a herramientas (80), tiempo de reloj (15 min), salida por llamada a herramienta (20,000 caracteres), ventana de Read (250 líneas), coincidencias de Grep (100), rutas de Glob (300) y contexto activo estimado (96,000 tokens).

El contexto se trata como un recurso presupuestado, no como una transcripción que no hace más que crecer. Por encima de un umbral, las carga sistemas de herramientas antiguas se reemplazan por entradas de una sola línea de un registro de ejecución determinista; si eso no basta, se eliminan turnos antiguos completos, porque el registro sigue conservando lo que hicieron. La instrucción del sistema, el contrato original de la tarea, los turnos recientes y el registro se conservan siempre. Nunca se gasta una llamada extra al modelo en resumir, y si el worker necesita un detalle que ha sido expulsado, vuelve a leer the archivo.

Todos los límites son configurables y los informa deepseek_health.

Referencia de configuración

Los ajustes marcados como reserved se validan al arrancar, pero todavía no se consumen.

Precedencia

environment variable > user config file > built-in default

La selección de modelo tiene además un nivel por encima de eso: una delegación puede nombrar su propio modelo, por lo que el orden completo es

per-task model > environment variable > user config file > built-in default

El modelo por tarea es el parámetro model de delegate_to_deepseek. Cuando allowed_models del servidor no está vacío, se trata de una lista de proporcionada, y una solicitud que nombre cualquier otra cosa se rechaza como blocked antes de cualquier llamada de API: la elección de modelo se reduce a lo que el operador haya permitido, exactamente igual que los modos de delegación se reducen a las capacidades del servidor.

Un ajuste ausente, malformado o contradictorio es un error. El servidor no degrade a un espacio de trabajo más amplio ni a una política más permisiva.

Si la configuración no se puede cargar, el proceso aún inicia y sigue respondiendo a deepseek_health, pero informa status: "error", mode: "disabled" y no hace trabajo. Ejecute deepseek-mcp --check para ver el mismo informe en la línea de comandos.

Ubicación del archivo de configuración

El archivo de configuración del usuario vive fuera de cualquier proyecto:

DEEPSEEK_MCP_CONFIG sobrescribe la ruta. Si está definida y el archivo no existe, el arranque falla en lugar de usar silenciosamente los valores por defecto. Un archivo de configuración ausente en la ubicación predeterminada es válido; un archivo vacío es válido; las claves desconocidas son un error.

Esquema del archivo de configuración

Cada clave es opcional.

{
  "model": "deepseek-chat",
  "allowed_models": ["deepseek-chat", "deepseek-reasoner"],
  "base_url": "https://api.deepseek.com/v1",
  "api_key_env": "DEEPSEEK_API_KEY",
  "workspace": "/absolute/path/to/project",
  "tools": {
    "enabled": ["Read", "Glob", "Grep", "Edit", "Write", "Run"],
    "max_write_bytes": 2000000,
    "allow_secret_paths": false,
    "secret_path_exceptions": []
  },
  "provider": {
    "timeout_seconds": 120,
    "max_retries": 3,
    "retry_base_delay": 0.5,
    "retry_max_delay": 8.0,
    "temperature": 0.0,
    "max_output_tokens": 4096
  },
  "budgets": {
    "max_turns": 24,
    "max_tool_calls": 80,
    "max_wall_seconds": 900,
    "max_tool_output_chars": 20000,
    "read_window_lines": 250,
    "max_grep_matches": 100,
    "max_glob_paths": 300,
    "max_context_tokens": 96000,
    "compaction_threshold_ratio": 0.7
  },
  "commands": {
    "default_timeout_seconds": 120,
    "max_timeout_seconds": 600,
    "extra_denied_executables": [],
    "extra_allowed_executables": [],
    "allow_unsafe_shell": false
  },
  "logging": { "level": "INFO", "file": null, "log_task_text": false },
  "debug": false
}

Una clave api_key se acepta aquí, pero no se recomienda: pone la clave en el disco y produce una advertencia al inicio. Prefiera api_key_env, que indica el nombre de la variable de entorno que se debe leer en su lugar.

allowed_models es optional lista allow opcional de nombres de modelo que una delegación puede solicitar. Cuando no está vacío, el model configurado debe estar en él (si no, los ajustes se contradicen), y un model por tarea que nombre algo fuera de la lista se rechaza como blocked antes de cualquier llamada API. Vacío significa que se acepta cualquier nombre de modelo bien formado.

Credenciales y endpoint

Sin clave de API no hay operación: el inicio notifica que el servidor está deshabilitado.

Espacio de trabajo

Si no se especifica un espacio de trabajo, la raíz se descubre subiendo desde el directorio de trabajo del proceso en busca de .git, .hg, .svn, pyproject.toml, package.json, go.mod o Cargo.toml. Si no se encuentra ninguna, se usa el propio directorio de trabajo y se registra una advertencia.

Un espacio de trabajo explícito que no exista, no se puede leer, no sea un directorio, sea relativo o sea la raíz del tamio de archivos es un error de arranque. Nunca se degrada al directorio de trabajo. El servidor no necesita estar dentro de su proyecto, y nunca modifica un proyecto para activarse.

Herramientas

Las herramientas habilitadas por défaut son todas menos NotebookEdit. NotebookEdit es un nombre reconocido sin implementación aún, por lo que habilitarlo es un error de arranque en lugar de una herramienta que se ofrece al worker y no puede usar. Read es obligatoria.

Los archivos internos de .git, .hg y .svn never se pueden leer ni escribir mediante lasal system tools; use, it use a read-only / run of git.

Límites de presupuesto

Todos se aplican por delegación y el deepseek_health los informá para que Claude pueda dimensionar una delegación antes de enviarla.

Superar un presupuesto termina la delegación con status: "budget_exceeded" y un motivo, después de notificar el trabajo que ya se haya realizado.

Proveedor

Los timeouts, los fallos de conexión, los 429 y los 5xx se reintentan. Un 4xx aparece inmediatamente, porque reintentar una clave incorrecta o una petición errónea solo hace perder el tiempo. Las redirecciones se rechazan por completo para que la cabecera Authorization no pueda reproducirse en otro host.

Política de comandos

Run ejecuta un array argv con shell=False. El ejecutable debe estar en una lista de permitidos, y los subcomandos peligrosos se rechazan estructuralmente. Use el campo commands.extra_allowed_executables del archivo de configuración para añadir una herramienta específica del proyecto, y extra_denied_executables para eliminar una. Una entrada extra de permitidos no puede volver a habilitar un programa denegado de forma estricta.

Rechazados por defecto: escalada de privilegios, instalación de paquetes, publicación, utilidades de red, shells e intérpretes de código en línea, operaciones destructivas del sistema de archivos, editores in situ y subcomandos git mutadores o remotos. Git de solo lectura (status, diff, log, show, ls-files, rev-parse, blame, …) está permitido.

Los lectores de archivos de propósito general como cat, head y grep están deliberadamente no incluidos en la lista de permitidos: serían un bypass de un solo comando a la lista de denegados de rutas secretas que Read, Glob y Grep aplican. Vuelva a añadir uno mediante extra_allowed_executables solo si lo acepta.

Registro

El registro de delegación es solo metadatos: nombre del evento, estado, modo, turno y recuentos de llamadas a herramientas, recuentos de tokens, duración y recuentos de archivos. Sin texto de tarea, contenidos de archivos, salida de comandos ni cuerpos de prompt. Los registros van a stderr, nunca a stdout — stdout transporta únicamente tráfico de protocolo MCP. La clave de API se elimina de cada registro como red de seguridad.

Postura de seguridad

Lea esta sección antes de decidir a qué apuntar el worker.

Las protecciones descritas aquí no cambian con las funciones de selección de modelo y análisis: contexto acotado con compactación, el sandbox del espacio de trabajo, la lista de permitidos de comandos, sin commit ni push, sin instalación de paquetes ni acceso a red por defecto, y un resultado estructurado con métricas de tokens y herramientas.

Lo que se aplica, en código:

• Cada ruta se resuelve contra una raíz de espacio de trabajo. Los enlaces simbólicos se siguen primero y el resultado es lo que se valida, por lo que un enlace fuera del árbol se rechaza. Los destinos de escritura tienen su directorio padre revalidado inmediatamente antes de la escritura.

• Un espacio de trabajo configurado explícitamente que falta o no es utilizable es un error de inicio. Nunca recurre silenciosamente a un directorio más amplio.

• Las rutas con secretos (.env, .env.*, *.pem, *.key, id_rsa, .netrc, .ssh/, .aws/ y similares) y los internos de .git/.hg/.svn están denegados a todas las herramientas, y se omiten de los resultados de búsqueda en lugar de ser simplemente ilegibles.

• El scope de una delegación restringe las escrituras. Las lecturas permanecen abiertas en todo el espacio de trabajo, porque el worker tiene que explorar para hacer su trabajo.

• Run usa shell=False. No hay shell, por lo que &&, |, $(...) y > llegan como texto de argumento literal y no pueden encadenar un segundo comando. El ejecutable debe estar en una lista de permitidos, los subcomandos peligrosos se rechazan estructuralmente sobre argv, los argumentos de ruta absoluta deben aterrizar dentro del espacio de trabajo, y un argumento que nombre una ruta denegada existente se rechaza.

• La instalación de paquetes, la publicación, las utilidades de red, la escalada de privilegios y los subcomandos git mutadores o remotos se rechazan por defecto. También los lectores de archivos de propósito general como cat y grep, que de otro modo serían un bypass de un solo comando a la lista de denegados de rutas secretas.

• Los subprocesos reciben un entorno con las credenciales eliminadas, por lo que la propia clave de API del worker no puede aparecer en la salida de comandos ni en un registro.

• Las escrituras son atómicas (archivo temporal, fsync, renombrado), por lo que una escritura interrumpida deja el archivo original intacto. Edit puede exigir el SHA-256 que Read devolvió, por lo que una edición obsoleta se rechaza en lugar de aplicarse.

• El prompt del sistema establece que el contenido del repositorio son datos, no instrucciones — y los límites anteriores se aplican en el lado del servidor, por lo que un archivo que le dice al worker que ignore sus instrucciones no puede concederle nada.

• Los registros son solo metadatos por defecto: evento, estado, recuentos, duraciones. Sin texto de tarea, contenidos de archivos, salida de comandos ni cuerpos de prompt. La clave de API se elimina de cada registro como red de seguridad.

Lo que esto no es: sandboxing adversarial a nivel de SO.

Esto es política a nivel de aplicación. Acota la categoría de acción que un worker confundido, equivocado o con inyección de prompt puede tomar. No es un límite de contención contra un adversario decidido, y los dos no son equivalentes.

Concretamente:

• Un ejecutor de pruebas permitido ejecuta el código de su proyecto. pytest importa el repositorio; make test ejecuta lo que diga el Makefile. Cualquier cosa alcanzable de esa manera es alcanzable, incluidos los archivos que la política de rutas habría rechazado.

• No hay aislamiento de procesos, sistema de archivos ni red — sin contenedor, sin bubblewrap ni seccomp, sin perfil de sandbox de macOS, sin objeto de trabajo de Windows, sin espacio de nombres de red. Un comando que está permitido se ejecuta con los mismos privilegios que el proceso del servidor.

• Las listas de denegados son estructurales en lugar de exhaustivas. Son la razón por la que la política de ejecutables es una lista de permitidos: los programas desconocidos se rechazan en lugar de asumirse seguros.

No apunte esto a un repositorio desde el que no ejecutaría pruebas, y no lo trate como un sustituto de revisar el diff.

Limitaciones conocidas

• NotebookEdit es un nombre de herramienta reconocido sin implementación. Habilitarlo es un error de inicio en lugar de una herramienta que se ofrece al worker y que no puede usar.

• commands.allow_unsafe_shell se valida pero no hace nada; no hay ejecución de shell en bruto.

• El worker no puede eliminar archivos. No hay herramienta de eliminación, y rm se rechaza.

• Sin sandbox a nivel de SO, como se indicó anteriormente.

• La estimación de contexto es una heurística de caracteres, calibrada al alza por el uso informado del proveedor. Es deliberadamente conservadora, no exacta.

• El comportamiento de búsqueda difiere ligeramente entre los motores ripgrep y Python puro, porque los dialectos de regex difieren. El motor utilizado se nombra en cada resultado.

• Windows está soportado y probado en CI, pero la terminación del grupo de procesos en timeout es de mejor esfuerzo allí en comparación con POSIX.

• Una delegación a la vez por llamada. No hay trabajos en segundo plano, ni memoria persistente del worker, ni commit o push automático de git.

Desarrollo

uv venv && uv pip install -e ".[dev]"
python -m pytest          # the full suite; no API key and no network needed
python -m ruff check .
python -m ruff format --check .
python -m mypy

La suite de pruebas nunca llama a una API de pago: un proveedor falso con script hace las veces, y las pruebas de integración de MCP ejecutan un subproceso de servidor real sobre stdio contra repositorios git temporales.

phases/ contiene la secuencia de implementación a partir de la cual se construyó este servidor, conservada como referencia.

GLOBAL_CLAUDE.md no forma parte de este código. Es un archivo de instrucciones de Claude Code a nivel de usuario que describe cuándo delegar — cópielo a ~/.claude/CLAUDE.md, o combínelo con el que ya tenga.

Licencia

MIT.