cursor-db-mcp (MCP Server)
An MCP server for querying, exporting, and analyzing Cursor IDE conversation history from the new workspaceStorage (SQLite) layout.
Highlights
- Query conversations across all workspaces (SQLite
state.vscdbunderworkspaceStorage) - Search and analyze messages, code blocks, and estimated code changes
- Export data in
json,csv, ormarkdown - Workspace utilities to list/filter recent workspaces
- Diagnostics tool to discover actual storage keys in your environment
Data sources and fallbacks
- Primary: legacy chat key (if present):
workbench.panel.aichat.view.aichat.chatdata - Heuristics: if the legacy key is missing, the server scans values for structures containing
conversations/messages/assistant/role. - Last resort: synthesizes conversations from
aiService.generations(user-side prompts). Optionally, it heuristically pairs items fromaiService.promptsas assistant replies to improve completeness.
Note: Depending on your Cursor version, assistant replies may not be locally persisted under known keys. The diagnostics tool can help you discover new keys. If you can share a confirmed key/path containing assistant messages, this server can be adapted quickly.
Installation
npm install
npm run build
Run MCP Inspector for local testing:
npm run inspector
The Inspector prints a local URL for interactive testing in your browser.
Configure in Cursor
Basic configuration:
{
"mcp.servers": {
"cursor-db": {
"command": "cursor-db-mcp",
"args": []
}
}
}
Custom workspaceStorage path:
{
"mcp.servers": {
"cursor-db": {
"command": "cursor-db-mcp",
"args": ["--workspace-path", "/custom/path/to/workspaceStorage"]
}
}
}
Available Tools
-
list_workspaces
- Input:
{ recent_days?: number } - Returns workspace list with hash, path, projectPath, lastModified
- Input:
-
get_workspace_conversations
- Input:
{ workspace_hash: string } - Use
list_workspacesto obtainworkspace_hash - Returns conversations for that workspace
- Input:
-
get_all_conversations
- Input:
{ limit?: number } - Returns cross-workspace conversations (sorted by updated time)
- Input:
-
search_conversations
- Input:
{ query: string, limit?: number } - Full-text search in titles and messages
- Input:
-
analyze_conversation
- Input:
{ conversation_id: string } - Returns stats (message counts, code blocks, estimated code changes)
- Input:
-
export_conversations
- Input:
{ format?: 'json'|'csv'|'markdown', conversation_id?: string, conversation_ids?: string[] } - Export all or a subset filtered by
conversation_id/conversation_ids
- Input:
-
analyze_code_statistics
- Input:
{ days?: number, group_by?: 'day'|'week'|'month'|'language'|'workspace' } - Aggregated metrics across the selected period
- Input:
-
diagnose_storage
- Input:
{ limit?: number } - Lists the largest
ItemTablekeys per workspace to help locate actual chat storage
- Input:
Ensuring assistant replies in results
- If your environment has a key containing full conversations (including assistant messages), the server will parse it directly.
- If not, the server falls back to
aiService.generations(user-only prompts) and tries to pair them withaiService.promptsas assistant replies heuristically. This improves completeness but may not perfectly reflect the original assistant responses. - To achieve exact assistant outputs, provide the confirmed storage key or path where Cursor persists assistant replies in your version.
Export formats
- JSON: raw conversations array
- CSV: one line per conversation with high-level metadata
- Markdown: per-conversation sections with messages and code blocks
Development
npm install
npm run build
npm run watch # optional: incremental builds
npm run inspector
Notes
- SQLite access uses
sqlite3. On some systems you may need build tools (e.g., Xcode CLT on macOS) installed. - Default workspace storage paths:
- macOS:
~/Library/Application Support/Cursor/User/workspaceStorage - Windows:
%APPDATA%/Cursor/User/workspaceStorage - Linux:
~/.config/Cursor/User/workspaceStorage
- macOS:
Troubleshooting
-
No conversations returned:
- Use
diagnose_storageto inspect keys. If no conversation-like key exists, your Cursor version may not store assistant replies locally. - The server will still return synthesized conversations from
aiService.generations(user prompts). Provide the real chat key to enable full parsing.
- Use
-
Permission/locking errors:
- Ensure Cursor is not locking the database when scanning. Try closing heavy operations in Cursor.
License
MIT — see LICENSE.