Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claude-history-mcp search my history for conversations about Python"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server that makes your Claude conversation history searchable. Export your conversations from claude.ai, ingest them into a local SQLite database with full-text search, and query them from Claude Code or Claude Desktop.
Python 3.11+
Related MCP server: ClaudeX
Go to claude.ai → Settings → Export Data. You'll receive an email with a download link containing a folder with conversations.json.
git clone https://github.com/fifeek0/claude-history-mcp.git
cd claude-history-mcp
# Ingest exported conversations into a local SQLite database
uv run python -m claude_history.ingest /path/to/exported/data/This creates history.db in the project root with FTS5 full-text search indexes.
Add to ~/.claude/.mcp.json:
{
"mcpServers": {
"claude-history": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/claude-history-mcp", "python", "-m", "claude_history"]
}
}
}Add to your claude_desktop_config.json:
{
"mcpServers": {
"claude-history": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/claude-history-mcp", "python", "-m", "claude_history"]
}
}
}Config file location:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Tool | Description |
| Full-text search across all messages. Supports FTS5 syntax ( |
| Get full conversation content with pagination (20 messages per page). |
| List topic categories with conversation and message counts. |
| Browse conversations by topic, sorted by date or size. |
| Quick overview: stats, first and last human message. |
Topics are assigned by keyword matching during ingestion. Edit src/claude_history/classify.py to customize the TOPIC_RULES dictionary:
TOPIC_RULES = {
"Your Topic": ["keyword1", "keyword2", ...],
...
}After editing, re-run the ingest command to reclassify all conversations.
Running ingest again deletes the existing database and rebuilds it from scratch — safe to re-run after a fresh export or after changing classification rules.
Browse conversations by topic and/or date.
Args: topic: Optional topic filter sort_by: "date" (newest first) or "size" (largest first) limit: Max results (default 20)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| topic | No | ||
| sort_by | No | date |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. It discloses sorting semantics ('date' newest first, 'size' largest first) and the default limit, but does not state that it is read-only, whether pagination exists, or any permission/auth constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded, with an Args section that is easy to scan. Minor waste/ambiguity is the 'and/or date' phrase, which is not backed by a parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple browse tool with an output schema, the parameter documentation is mostly sufficient. However, it lacks usage guidance and contains a misleading date-filter implication, so it is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents all three parameters and adds sort_by values beyond the schema, but the opening claim 'by topic and/or date' suggests a date filter that the schema does not contain, creating ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Browse) and resource (conversations) with filter dimensions. It does not differentiate from siblings such as search_history, so an agent still has to infer which tool is appropriate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use, when-not-to-use, or alternative guidance is given. The phrase 'by topic and/or date' describes scope but not selection context against list_all_topics, search_history, or the other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a quick overview of a conversation: stats, first and last human message.
Args: uuid: Conversation UUID
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It hints at read-only behavior via 'Get' and discloses that the payload is a compact summary rather than full history, but says nothing about permissions, cost, truncation of long conversations, or behavior on a missing UUID.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core sentence is tight and front-loaded with the verb and resource. The 'Args:' block is boilerplate that largely restates the schema, but it is short enough not to bloat the definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description is not obligated to explain return values and it correctly signals what the payload contains. However, with no annotations and no usage guidance, a 1-parameter tool that competes with four siblings is only minimally specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only source for the single parameter, and it does clarify that the UUID identifies a conversation. Beyond that identifier semantics, it adds nothing (no format, sourcing, or error behavior for an invalid UUID).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Get') and resource ('overview of a conversation') and enumerates the returned content (stats, first and last human message), which implicitly separates it from get_conversation_messages. It does not explicitly name or contrast with any sibling, but the scope is clear enough to select it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this instead of get_conversation_messages, browse_conversations, or search_history. The agent must infer from the word 'summary' that this is the cheap first-look option.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full conversation content with pagination (20 messages per page).
Args: uuid: Conversation UUID page: Page number (default 1)
Returns conversation metadata and messages for the requested page.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| uuid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses a fixed page size of 20 messages and that it returns both metadata and messages, but says nothing about permissions, error cases, or behavior for out-of-range pages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core capability and pagination limit are front-loaded in the first sentence, and the arg list is compact. The final 'Returns...' line is somewhat redundant given an output schema exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with an output schema present, the description covers the essential call-time facts: what it fetches, the fixed page size, and both parameters. The missing piece is routing guidance against its four siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it defines uuid as the Conversation UUID and page as a page number defaulting to 1, plus the non-schema fact that pages contain 20 messages. It could still clarify what happens when page exceeds the available range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get full conversation content') and adds a scope detail (pagination, 20 per page), so an agent knows exactly what it retrieves. It does not, however, contrast itself with siblings like conversation_summary or browse_conversations, leaving differentiation to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus the alternatives (browse_conversations, conversation_summary, search_history). The description only implies usage through its pagination note, and offers no prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all conversation topic categories with counts.
Returns topic names, conversation counts, and total message counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses what is returned (names, conversation counts, message counts) and 'List' implies a read-only operation, but it says nothing about permissions, pagination, or ordering behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and resource, and every clause earns its place by describing the returned data. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complexity is very low (no parameters) and an output schema exists, so return values need not be re-explained. The description is nearly sufficient; only the lack of usage context keeps it from a full score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline of 4 applies. There is no parameter semantics to compensate for and the description adds nothing that could be missing here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('all conversation topic categories') plus the returned data ('counts'). This is clearly distinct from the sibling tools (browse_conversations, search_history, etc.), which all operate on conversations rather than the topic taxonomy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, prerequisites, or routing to alternatives. An agent must infer that this is for obtaining an overview of topic categories; no exclusion or context is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across all Claude conversation messages using full-text search.
Args: query: Search query (supports FTS5 syntax: AND, OR, NOT, "phrases") topic: Optional topic filter (ERP/NAV, AI/ML, DevOps, Business/EVORA, Development, Hackathon, Personal, Other) limit: Max results (default 10)
Returns matching conversations with text snippets showing where the match occurred.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| topic | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses query syntax (FTS5 operators) and the return format (snippets showing match location), but says nothing about scope limits, pagination, permissions, or performance characteristics of searching all messages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose sentence followed by a compact Args block and a one-line Returns note. The Args section partially duplicates the schema but earns its place by adding syntax and enum details; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter search tool with an output schema present, the definition covers purpose, all parameters, and match behavior adequately. Only scope bounds (e.g., whether all conversations or a window) and pagination are left unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does: it explains query FTS5 syntax, enumerates all eight valid topic values not present in the schema, and documents the limit default. Every parameter gains meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource+mechanism: 'Search across all Claude conversation messages using full-text search.' This clearly distinguishes the search action from sibling browse/list/get tools by name and scope, though it never explicitly names an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this versus browse_conversations, list_all_topics, or get_conversation_messages. The only implicit cue is that a query is required, but no conditions or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0browse_conversationsconversation_summaryget_conversation_messageslist_all_topicssearch_historyScored across 5 tools
Each tool targets a distinct operation: listing topics, browsing conversations, summarizing a conversation, searching messages, and fetching full messages. The uuid-based summary and full-message tools are clearly differentiated by scope.
Mostly snake_case with verb_noun pattern (browse_conversations, search_history, get_conversation_messages), but conversation_summary is a noun phrase and list_all_topics inserts 'all', creating minor inconsistency.
Five tools is a well-scoped, focused set for a read-only conversation history server; no tool feels redundant and the count matches the domain.
Core read operations (topics, browse, summary, search, full messages) are covered, but browse_conversations lacks pagination offset and a date filter despite the description, leaving minor gaps.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Parse, extract, split, and ask over digital PDFs (text layer, no OCR) from Cursor and Claude.
Personal CRM for Claude. Contacts live as plain-text files in your own Google Drive.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.