Cliente MCP de Eve

eve-client es el instalador local y la CLI de integración para conectar herramientas de IA compatibles con el servicio de memoria alojado de Eve.

Detecta herramientas locales, configura MCP, instala archivos de prompts y hooks gestionados por Eve donde sea compatible, gestiona la autenticación y puede verificar, reparar o eliminar la integración más adelante. También puede importar el historial local desde clientes compatibles.

Cómo funciona Eve

Cuando ejecutas eve install, Eve configura cuatro hooks de ciclo de vida que se ejecutan automáticamente; no se necesitan comandos durante tus sesiones.

Los hooks de ciclo de vida están disponibles en Claude Code y Gemini CLI. Eve también se conecta a Codex CLI y otros clientes compatibles con MCP mediante la siembra de prompts, para que obtengas memoria en todas tus herramientas.

Related MCP server: Sovereign Universal Memory MCP

Inicio rápido — 5 minutos

1. Obtén un espacio de trabajo de Eve

Solicita acceso en evemem.com. Después del aprovisionamiento, inicia sesión y crea una clave API en evemem.com/app/overview.

2. Instala el cliente

uv tool install git+https://github.com/sherifkozman/eve-mcp.git

¿No tienes uv? Usa:

pipx install git+https://github.com/sherifkozman/eve-mcp.git

Verifica: eve version

3. Conecta Claude Code (cambia --tool gemini-cli por Gemini CLI)

eve connect --tool claude-code --api-key <your-eve-api-key>

Esto combina la autenticación, la instalación y la verificación. Para ver el paso a paso, consulta API key flow a continuación.

Salida esperada:

✓ MCP config written
✓ CLAUDE.md companion updated
✓ Lifecycle hooks configured — Eve auto-injects memory context on every session
✓ Eve memory is connected and responding

¿Qué acaba de pasar? Eve instaló cuatro hooks de ciclo de vida. A partir de este momento, cada sesión de Claude Code comienza con tu contexto de memoria precargado y termina con los nuevos aprendizajes capturados. Nunca necesitas pedirle a Claude que use Eve.

Si eve connect falla: ejecuta eve doctor --tool claude-code y revisa la salida de diagnóstico. Abre un issue en github.com/sherifkozman/eve-mcp.

Prueba la memoria entre sesiones

En Claude Code, dile a Claude:

"Recuerda que uso PostgreSQL con una tabla de usuarios: columnas email y created_at."

Inicia una nueva sesión de Claude Code y pregunta:

"¿Qué configuración de base de datos mencioné?"

Claude la recordará a través de Eve. ✓

Consulta examples/ para ver fragmentos de configuración de MCP manuales (no se necesita instalador).

Instalación

Antes de instalar el cliente, obtén un espacio de trabajo de Eve:

• Solicita acceso: https://evemem.com

• Después de que tu espacio de trabajo esté aprovisionado, inicia sesión en el panel de control de Eve:

  • https://evemem.com/app/overview

• Si planeas usar la autenticación con clave API, crea o rota una clave de inquilino desde el flujo de configuración de administrador/usuario de Eve antes de conectar tu cliente.

Desde GitHub ahora

Preferido:

uv tool install git+https://github.com/sherifkozman/eve-mcp.git

Alternativa:

pipx install git+https://github.com/sherifkozman/eve-mcp.git

O a través del instalador bash independiente:

curl -fsSL https://raw.githubusercontent.com/sherifkozman/eve-mcp/main/install.sh | bash

Luego confirma:

eve version
eve --help

Configuración manual (sin instalador)

Consulta examples/ para ver fragmentos de configuración de MCP listos para copiar y pegar para Claude Code, Gemini CLI y Codex CLI.

Desde PyPI más adelante

Una vez publicado, la instalación del paquete será:

uv tool install eve-client

o:

pipx install eve-client

Qué hace el cliente de Eve

• detecta clientes de IA locales compatibles

• muestra un plan de instalación antes de cambiar archivos

• escribe la configuración de MCP gestionada por Eve

• instala archivos de prompt/acompañamiento donde sea compatible

• instala cuatro hooks de ciclo de vida que inyectan automáticamente el contexto de memoria en cada sesión (SessionStart, UserPromptSubmit, PreCompact, Stop)

• almacena la autenticación localmente usando almacenamiento de credenciales basado en archivos

• proporciona comandos eve memory search y eve memory status para acceso directo a la memoria

• verifica, repara, revierte y desinstala los cambios gestionados por Eve

• importa el historial de conversaciones local a Eve desde clientes compatibles

Importación de historial local

Fuentes de importación compatibles actualmente:

• Claude Code

• Codex CLI

• Gemini CLI

Comandos principales:

eve import scan --source claude-code
eve import preview --source claude-code --path <session_file>
eve import jobs                              # list scan jobs
eve auth login --tool claude-code
eve import upload --job <scan_job_id> --use-auth-from claude-code
eve import runs                              # list upload runs
eve import resume --run <run_id>
eve import cleanup --days 30
eve import cleanup --days 30 --apply

Cómo funciona:

• analiza el historial local en tu máquina

• sube lotes normalizados al servicio gestionado de Eve

• mantiene un libro mayor de SQLite local para trabajos de escaneo, ejecuciones de carga, reproducción y reanudación

• admite la limpieza de prueba (dry-run) de ejecuciones de importador local antiguas completadas de forma predeterminada

Mantenimiento del importador:

• eve import cleanup es un comando de mantenimiento de libro mayor local genérico, no una función de fuente de importación específica del cliente

Nota sobre autenticación:

• evita pasar secretos directamente en la línea de comandos cuando sea posible

• prefiere eve auth login ... primero, luego ejecuta los comandos del importador sin repetir la clave API

• en un shell interactivo, eve auth login --tool claude-code solicita la clave de forma segura

Nota sobre el despliegue actual:

• la corrección y la reanudación son sólidas

• las importaciones muy grandes, especialmente las que dependen mucho de Claude, pueden seguir siendo más lentas de lo ideal mientras se siguen ajustando los valores predeterminados de procesamiento por lotes

Clientes compatibles

Claude Code

Compatible hoy:

• Configuración MCP

• Archivo de acompañamiento CLAUDE.md

• Hooks gestionados por paquetes

• Soporte de importador: scan, preview, upload, resume

Ruta de autenticación principal hoy:

• Clave API de Eve

Gemini CLI

Compatible hoy:

• Configuración MCP

• Archivo de acompañamiento GEMINI.md

• Hooks gestionados por paquetes

• Soporte de importador: scan, preview, upload, resume

Ruta de autenticación principal hoy:

• Clave API de Eve

Codex CLI

Compatible hoy:

• Configuración MCP

• Inicio de sesión OAuth propiedad de Eve

• Inyección de token de portador en tiempo de ejecución

• Soporte de importador: scan, preview, upload, resume

Ruta de autenticación principal hoy:

• Eve OAuth

Importante:

• El inicio de sesión nativo de Codex MCP no es la ruta compatible de Eve

Claude Desktop

No configurado automáticamente de forma local para Eve alojado.

Requisitos de autenticación

Necesitas un espacio de trabajo de Eve y, o bien:

• una clave API de Eve, o

• acceso OAuth de Eve para flujos compatibles

Expectativas de autenticación actuales:

• Claude Code: Clave API

• Gemini CLI: Clave API

• Codex CLI: Eve OAuth

El flujo de navegador OAuth existe para más clientes, pero todavía es experimental fuera de la ruta de Codex y no debe tratarse como el flujo de instalador de producción predeterminado todavía.

Uso básico

Primera ejecución

eve quickstart
eve connect --tool claude-code
eve verify --tool claude-code

Flujo de clave API

eve auth login --tool claude-code --api-key <eve-key>
eve install --tool claude-code --apply --yes  # --apply writes config, --yes skips confirmation
eve verify --tool claude-code

Flujo OAuth de Codex

eve auth login --tool codex-cli --auth-mode oauth
eve install --tool codex-cli --auth-mode oauth --apply --yes
eve verify --tool codex-cli --auth-mode oauth

Comandos de memoria

eve memory search "what database do we use" --context naya
eve memory search "auth patterns" --limit 5 --json
eve memory status
eve memory status --json

Comandos comunes

eve quickstart
eve connect
eve install --dry-run
eve install --apply --yes --tool claude-code
eve status
eve doctor
eve verify
eve repair --tool gemini-cli --apply --yes
eve uninstall --tool claude-code --yes
eve run --tool codex-cli -- exec "Use Eve memory to search for my latest preference."

Configuración manual de MCP

Si no quieres que el instalador edite la configuración del cliente por ti, añade el servidor MCP de Eve alojado manualmente.

Punto final de MCP alojado compartido

https://mcp.evemem.com/mcp

Claude Code / Gemini CLI (Clave API)

Usa una clave API de inquilino del panel de administración de Eve.

{
  "eve-memory": {
    "type": "http",
    "url": "https://mcp.evemem.com/mcp",
    "headers": {
      "X-API-Key": "eve_<tenant>_...",
      "X-Source-Agent": "claude_code"
    }
  }
}

Para Gemini, mantén la misma estructura y cambia:

X-Source-Agent = gemini_cli

Codex CLI (OAuth)

Codex debe usar un token de portador propiedad de Eve, no codex mcp login nativo.

[mcp_servers.eve-memory]
url = "https://mcp.evemem.com/mcp"
bearer_token_env_var = "EVE_CODEX_BEARER_TOKEN"
startup_timeout_sec = 60

[mcp_servers.eve-memory.headers]
X-Source-Agent = "codex_cli"

Recurso OAuth:

https://mcp.evemem.com/mcp

La siembra de prompts de Codex pertenece al AGENTS.md del proyecto activo. Eve gestiona su propio bloque marcado dentro de ese archivo en lugar de crear un archivo secundario paralelo.

Otros clientes MCP

Para otros clientes MCP remotos, la configuración mínima de trabajo es:

1. URL de MCP:

https://mcp.evemem.com/mcp

2. Un encabezado de agente de origen:

X-Source-Agent: your_client_name

3. Elige un estilo de autenticación:

• Clave API:

X-API-Key: eve_<tenant>_...

• Portador OAuth:

Authorization: Bearer <token>

4. Para clientes con capacidad OAuth, usa este identificador de recurso:

https://mcp.evemem.com/mcp

5. Alcances requeridos:

memory.read
memory.write

Si el cliente admite un archivo de instrucciones de acompañamiento, apúntalo al archivo de instrucciones activo para esa herramienta en lugar de inventar un segundo archivo paralelo.

Qué ruta de autenticación usar

• Claude Code: Clave API

• Gemini CLI: Clave API

• Codex CLI: Eve OAuth

Si quieres que Eve gestione la configuración, los prompts, los hooks y la verificación por ti, usa eve connect en lugar de editar archivos manualmente.

Modelo de seguridad

• sin mutación silenciosa del perfil de shell

• sin hooks no documentados

• sin sobrescritura de archivos de instrucciones creados por el usuario

• copia de seguridad y seguimiento de manifiesto antes de la mutación

• soporte explícito de reversión y desinstalación

• la desinstalación elimina las credenciales y entradas de herramientas gestionadas por Eve, y advierte cuando un archivo propiedad de Eve modificado por el usuario requiere revisión manual

Desarrollo

Ejecutar pruebas:

uv run pytest --cov=eve_client --cov-report=term-missing -q tests

Construir artefactos de Python:

uv build .

Verificar artefactos de construcción:

uvx twine check dist/*

Construir artefactos de lanzamiento independientes:

bash scripts/build-eve-client-release.sh

Licencia

Apache-2.0. Consulta LICENSE.