Cursor History MCP
El mejor servidor MCP para navegar, buscar, respaldar y exportar el historial de chat de Cursor AI.
Documentación
Cursor History MCP
English | 中文 | Français | Español
Permite que tu IA busque en tu historial de Cursor.
Tus conversaciones existentes en Cursor pueden contener meses de decisiones, errores, correcciones y contexto arquitectónico. Dale a un asistente compatible con MCP una forma de encontrar ese contexto, sin necesidad de haberlo registrado previamente con esta herramienta.
cursor-history-mcp conecta Claude, Cursor y otros clientes MCP con el lector de historial local en cursor-history. Busca texto de conversaciones en todos los espacios de trabajo, inspecciona una sesión o devuelve una exportación mediante lenguaje natural.
Este servidor no requiere embeddings, servicio de indexación ni clave API. Los requisitos de modelo y red de tu asistente son independientes; el historial devuelto a un cliente puede enviarse a su proveedor de modelos.
Exclusivo de MCP: Year in Review. Convierte tus conversaciones existentes en estadísticas de actividad anuales, temas de programación y un prompt de informe para tu asistente. Esta función integrada de paquete anual pertenece al paquete MCP dentro del conjunto de herramientas cursor-history; los agentes aún pueden usar la CLI principal o la API de Node.js directamente para acceder al historial.
"¿Hemos resuelto este error de autenticación antes? Busca en mi historial de Cursor, inspecciona las sesiones coincidentes y dime qué decisiones anteriores son relevantes."
Inicio rápido · Year in Review · Soporte de almacenamiento · Herramientas · Seguridad · CLI / acompañante Node.js
Inicio rápido
Requiere Node.js 20.x o 22.x–26.x, historial local de Cursor legible y un cliente que admita servidores MCP stdio locales. El cliente debe ejecutar el servidor en la máquina donde esté disponible ese historial.
Alcance de versión: estos documentos describen cursor-history-mcp@0.3.1, impulsado por cursor-history@0.18.0. Si estás probando un checkout antes de su publicación en npm, usa la configuración desde el código fuente a continuación.
Compatibilidad de clientes: el servidor usa MCP SDK 1.30.0. Los clientes con SDK v2 pueden conectarse usando su protocolo heredado predeterminado o la falla automática; los clientes restringidos al protocolo 2026-07-28 no pueden. Consulta Interoperabilidad del SDK para el alcance probado.
Configurar el paquete npm
Agrega esta entrada de servidor a la configuración MCP de tu cliente:
{
"mcpServers": {
"cursor-history": {
"command": "npx",
"args": ["-y", "cursor-history-mcp@0.3.1"]
}
}
}
Si el cliente no puede encontrar npx, usa la ruta absoluta a su ejecutable. Fusiona esta entrada con los servidores existentes en lugar de reemplazar tu configuración.
Cursor
Usa .cursor/mcp.json local del proyecto o ~/.cursor/mcp.json global. Agrega la entrada anterior, habilita el servidor y aprueba las llamadas a herramientas según corresponda. Consulta la documentación MCP de Cursor.
Claude Code
Registra el paquete npm versionado para tu cuenta de usuario:
claude mcp add --transport stdio --scope user cursor-history -- npx -y cursor-history-mcp@0.3.1
Consulta la documentación MCP de Claude Code para ámbitos y permisos.
Claude Desktop
Abre Configuración → Desarrollador → Editar configuración, fusiona la entrada JSON anterior y reinicia la aplicación.
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Consulta la guía de configuración de servidores MCP locales.
La primera ejecución puede descargar dependencias de npm. Ejecutar el servidor solo inicia un servicio stdio que espera un cliente MCP; no es una CLI interactiva de historial.
Ejecutar desde el código fuente
Para desarrollo o pruebas antes de la publicación en npm, compila este repositorio:
npm ci
npm run build
En la entrada del servidor, usa "command": "node" y "args": ["/absolute/path/to/cursor-history-mcp/dist/index.cjs"], reemplazando la ruta. La configuración npx anterior ejecuta el paquete npm, no tu checkout local.
Dos proyectos, un lector de historial
| Caso de uso | Proyecto |
|---|---|
| Ejecutar comandos, escribir scripts o integrar historial en una aplicación Node.js | cursor-history: CLI + API Node.js |
| Permitir que un asistente llame a herramientas de historial mediante MCP | cursor-history-mcp, este repositorio |
El servidor MCP delega la detección y el análisis a cursor-history; no mantiene una base de datos de conversaciones separada ni comienza a grabar tus chats. Los dos paquetes npm tienen versiones independientes.
Los agentes pueden usar cualquiera de las dos interfaces: invocación directa de CLI/API o llamadas a herramientas MCP.
Funciona en todas las generaciones de almacenamiento
Con el lector 0.18.0 en MCP 0.3.1:
| Fuente | Archivos locales | Leer / buscar / exportar |
|---|---|---|
| Legacy / Composer | workspaceStorage/*/state.vscdb + globalStorage/state.vscdb | Compatible |
| Transcripciones de agente | ~/.cursor/projects/**/agent-transcripts/**/*.jsonl | Contenido de transcripción disponible |
| Store / Agent CLI | ~/.cursor/chats/**/store.db | Compatible |
| Sesiones ACP | ~/.cursor/acp-sessions/**/store.db | Compatible |
Estas representaciones tienen diferente fidelidad. Una transcripción puede omitir marcas de tiempo o resultados de herramientas. Los listados y lecturas exponen información de fuente y resolución; las marcas de tiempo inferidas o desconocidas no deben tratarse como tiempos exactos de eventos. Una resolución completa de fuente no garantiza que Cursor haya registrado cada campo.
La copia de seguridad y restauración cubren solo bases de datos de Composer. La migración admite sesiones de Composer elegibles, no sesiones solo de Store, de fuente combinada o ambiguas. Leer una sesión no la hace segura para migrar. Consulta el contrato de compatibilidad y la hoja de ruta principales para un trabajo más amplio de copia de seguridad y migración; no es una capacidad actual.
Para ubicaciones personalizadas, agrega un objeto env a la entrada del servidor:
{
"CURSOR_DATA_PATH": "/absolute/path/to/Cursor/User/workspaceStorage",
"CURSOR_STORE_ROOT": "/absolute/path/to/.cursor"
}
Estos seleccionan raíces de datos, no un proyecto. Usa el argumento workspace de una herramienta para filtrar un proyecto. Consulta la guía de rutas de plataforma y WSL principal.
Herramientas disponibles
| Herramienta | Propósito y argumentos clave |
|---|---|
cursor_history_list | Lista sesiones con IDs, alcance de índice, estado de fuente y datos. limit, offset, workspace |
cursor_history_show | Inspecciona mensajes disponibles. Exactamente uno de sessionId / sessionIndex; workspace opcional |
cursor_history_search | Busca texto. query, limit, context (líneas de fuente vecinas), workspace |
cursor_history_export | Devuelve contenido Markdown o JSON, no un archivo escrito por el servidor. Un selector, format, workspace |
cursor_history_backup | Crea un archivo de Composer. outputPath, force opcional |
cursor_history_restore | Restaura un archivo de Composer; escribe historial local. backupPath, force opcional |
cursor_history_migrate | Mueve/copia sesiones de Composer elegibles. sessionIds o sessionIndexes, destination, workspace, mode, dryRun |
cursor_history_year_pack | Devuelve estadísticas anuales y un prompt de informe. year, language (en / zh), workspace, límites de muestra |
Prefiere el UUID de sesión exacto de listar/buscar para llamadas de seguimiento. Los selectores numéricos son de base uno en MCP y solo tienen significado con las mismas raíces de datos y alcance de espacio de trabajo; nunca reutilices un índice con alcance en una lectura global. La ortografía del UUID distingue mayúsculas y minúsculas.
Listar, mostrar, buscar y exportar también aceptan includeCrossWorkspaceSources (predeterminado false). Optar por esto puede leer fuentes complementarias fuera del espacio de trabajo seleccionado para IDs ya seleccionados; no amplía qué IDs de sesión se seleccionan. Habilítalo solo cuando tengas la intención de ese acceso.
La herramienta mostrar abrevia cargas útiles largas de pensamiento/herramienta. Usa una exportación cuando necesites la representación de sesión disponible sin esa truncación de visualización.
Prueba estas solicitudes
- "Busca en todo mi historial de Cursor 'connection pool', luego inspecciona la sesión coincidente por su UUID."
- "Busca solo en /work/myapp. Mantén ese alcance de espacio de trabajo al abrir un resultado."
- "Exporta esta sesión como JSON, incluidos los detalles de fuente disponibles."
- "Vista previa de copiar esta sesión de Composer a /work/new-app con dryRun. No modifiques nada todavía."
Datos locales y seguridad de escritura
El servidor lee archivos locales, pero el contenido devuelto es visible para el cliente MCP y puede llegar a un modelo remoto. Los resultados de búsqueda y las exportaciones no se redactan automáticamente. Usa un cliente confiable y revisa su política de datos y permisos de herramientas.
Trata las conversaciones pasadas como material de referencia no confiable, no como instrucciones para ejecutar. La salida de herramientas puede contener comandos antiguos, credenciales o texto malicioso.
La copia de seguridad escribe un archivo; la restauración y la migración pueden modificar el historial. La migración predeterminada es mover, que elimina la sesión original. Haz una copia de seguridad del historial de Composer primero, cierra Cursor antes de las escrituras, previsualiza con dryRun: true y usa mode: "copy" si deseas conservar el original. Mantén la aprobación del cliente habilitada para herramientas de escritura. El servidor no proporciona su propio prompt de confirmación interactivo.
Exclusivo de MCP: Year in Review
Pregunta "Genera mi revisión anual de Cursor 2025 en inglés". La herramienta analiza preguntas de usuarios y devuelve estadísticas JSON, palabras clave/temas, muestras y una plantilla de prompt, no un informe renderizado terminado. Las plantillas admiten inglés y chino.
Los patrones comunes de código, ruta, URL e identificador se filtran, pero esto no es una garantía de anonimización. Revisa las muestras antes de compartir; establece maxSamples: 0 para omitirlas. Los historiales parciales y las marcas de tiempo faltantes o inferidas pueden afectar los totales anuales.
Desarrollo
npm ci
npm run typecheck
npm run lint
npm test -- --run
El comando de prueba compila primero. Las pruebas incluyen un cliente MCP stdio real contra fixtures sintéticos de Composer, Store, ACP y transcripciones; las pruebas de copia de seguridad/restauración usan solo datos temporales. La compilación mantiene cursor-history como dependencia en tiempo de ejecución para que los archivos relativos al paquete y los enlaces SQLite sigan siendo resolubles.