Unified History MCP
This server provides configurable full-text search across historical data from multiple domains: agent session logs, meeting transcripts, notification files, command history, and runtime logs. Capabilities include:
Search across one or all domains with options for FST-accelerated or regex search, date range filtering, role filtering (for sessions: user/assistant/tool), speaker filtering (for transcripts), case sensitivity, context lines, and result limits.
List available files and their metadata within a domain, with optional date filtering and entry limits.
Read specific entries from a file or directory, with role/speaker filtering and latest-first ordering.
Summarize entries in sessions or transcripts using AI-generated summaries.
Rebuild FST indexes for fast search across configured domains.
Search command history with plain text or regex, case sensitivity, and limits.
Search runtime logs with query, regex, case sensitivity, and optional log level filtering (e.g., WARNING, ERROR, DEBUG, INFO).
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., "@Unified History MCP search all history for 'deployment failure'"
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.
Unified History MCP
Config-driven MCP server for cross-domain full-text search across agent session logs, meeting transcripts, and notification files.
Quick Start
# Install from source (PyPI package coming soon)
pip install git+https://github.com/jmars/unified-history-mcp.git
# Create a config file at ~/.config/unified-history-mcp/config.toml
# or use the example as a starting point:
cp config.example.toml ~/.config/unified-history-mcp/config.toml
# Start the server
unified-history-mcpAdd to your MCP client configuration:
{
"mcpServers": {
"unified-history": {
"command": "unified-history-mcp"
}
}
}Related MCP server: Unified History MCP
Configuration
Configuration is loaded from the first existing location:
$UNIFIED_HISTORY_CONFIGenvironment variable~/.config/unified-history-mcp/config.toml./unified-history.toml(current working directory)
Domain Configuration
Each [domains.X] section defines a searchable domain:
Field | Type | Default | Description |
| string | required | Root directory for this domain's files |
| string |
| Glob pattern for file discovery |
| string |
|
|
| string[] |
| Allowed extensions (e.g. |
| string |
| Extractor: |
| string | (extractor) | Renderer override |
| string |
| Human label: "session", "transcript", etc. |
| string |
| Path or name of the FST indexer binary |
| string | (dir) | Override for index directory |
| string | — | JSON field for date extraction (jsonl only) |
| string[] |
| Supported filters: |
Global Configuration
Section | Field | Description |
|
| Path to command history file |
|
| Path to runtime log file |
MCP Tools
search(domain, query, ...)
Full-text search with FST fast path and regex fallback.
Parameter | Type | Default | Description |
| string |
| Domain or |
| string |
| Search text or regex pattern |
| int |
| Maximum total matches |
| string | — | Start date (YYYY-MM-DD) |
| string | — | End date (YYYY-MM-DD, inclusive) |
| bool |
| Treat query as regex |
| int |
| Surrounding context lines per match |
| bool |
| Case-sensitive matching |
| int |
| Max matches from any single file |
| string | — | [sessions] Filter by role: user, assistant, tool |
| string | — | [transcripts] Filter by speaker name |
list_domain(domain, date_from, date_to, max_results)
List available files in a domain with metadata.
Parameter | Type | Default | Description |
| string | — | Domain to list |
| string | — | Start date (YYYY-MM-DD) |
| string | — | End date (YYYY-MM-DD, inclusive) |
| int |
| Maximum entries to show |
read(domain, id, max_entries, role, speaker)
Read entries from a domain file.
Parameter | Type | Default | Description |
| string | — | Domain |
| string | — | File/directory name or unique prefix |
| int |
| Maximum entries (newest first) |
| string | — | [sessions] Filter by role |
| string | — | [transcripts] Filter by speaker name |
summary(domain, id)
Get the AI-generated summary for a domain entry.
Parameter | Type | Description |
| string | Domain (sessions, transcripts) |
| string | File/directory name or unique prefix |
rebuild(domain)
Rebuild FST indexes for configured domains.
Parameter | Type | Default | Description |
| string |
| Domain or |
search_history(query, max_results, regex, case_sensitive)
Search the command history file.
Parameter | Type | Default | Description |
| string | — | Search text or regex pattern |
| int |
| Maximum matches |
| bool |
| Treat query as regex |
| bool |
| Case-sensitive matching |
search_log(query, max_results, regex, case_sensitive, level)
Search the runtime log file.
Parameter | Type | Default | Description |
| string | — | Search text or regex pattern |
| int |
| Maximum matches |
| bool |
| Treat query as regex |
| bool |
| Case-sensitive matching |
| string | — | Filter by log level |
How It Works
Configuration — TOML file defines domains, their directories, extractors, and renderers.
Domain Discovery — Files are discovered via glob patterns with extension filtering.
Fast Path (FST) — If the optional
fst-indexerbinary is installed and indexes are built (via therebuildtool), searches use the blazing-fast FST index.Slow Path (Regex) — Falls back to line-by-line regex scanning across files when FST is unavailable.
Extractors — Produce text entries for FST indexing from different file formats (JSONL, TXT, Tactiq transcripts, notifications).
Renderers — Format entries for human-readable display in search results, listings, and read output.
Development
git clone https://github.com/jmars/unified-history-mcp.git
cd unified-history-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytestContributing
Contributions are welcome! See CONTRIBUTING.md for guidelines on setting up the dev environment, running tests, and submitting pull requests.
License
MIT — see LICENSE.
Available Tools
7 toolslist_domainA
List available files in a domain with metadata and summaries.
Args: domain: Domain to list (sessions, transcripts, notifications) date_from: Optional start of date range (YYYY-MM-DD) date_to: Optional end of date range (YYYY-MM-DD, inclusive) max_results: Maximum entries to show (default 50)
Inputs: domain (required), date_to, date_from, max_results. Returns: result
readB
Read entries from a domain file.
Args: domain: Domain (sessions, transcripts, notifications) id: File/directory name or unique prefix max_entries: Maximum entries to return, newest first (default 50) role: [sessions] Filter by role: user, assistant, tool speaker: [transcripts] Filter by speaker name
Inputs: id (required), domain (required), role, speaker, +1 more. Returns: result
rebuildA
Rebuild FST indexes for configured domains.
Args: domain: Domain to rebuild, or "all" for all configured domains
Inputs: domain. Returns: result
searchA
Search across domains with FST-backed full-text search.
Domains: sessions — Vibe coding session conversations transcripts — Meeting transcripts (supports speaker filter) notifications — Teams notification logs all — Search across all three domains at once (default)
Args: domain: Domain to search, or "all" for cross-domain (default: all) query: Search text (or regex pattern if regex=True) max_results: Maximum total matches to return (default 20) date_from: Optional start of date range (YYYY-MM-DD) date_to: Optional end of date range (YYYY-MM-DD, inclusive) regex: If True, treat query as a regex pattern context_lines: Lines of surrounding context per match (default 2) case_sensitive: If True, match case-sensitively (default False) max_matches_per_file: Max matches from any single file (default 5) role: [sessions] Filter by role: user, assistant, tool speaker: [transcripts] Filter by speaker name
Inputs: role, query, regex, domain, +7 more. Returns: result
search_historyA
Search the Vibe command history (vibehistory file).
Args: query: Search text (or regex pattern if regex=True) max_results: Maximum matches to return (default 30) regex: If True, treat query as a regex pattern case_sensitive: If True, match case-sensitively (default False)
Inputs: query (required), regex, max_results, case_sensitive. Returns: result
search_logA
Search the Vibe runtime log (vibe.log).
Args: query: Search text (or regex pattern if regex=True) max_results: Maximum matches to return (default 30) regex: If True, treat query as a regex pattern case_sensitive: If True, match case-sensitively (default False) level: Filter by log level: WARNING, INFO, ERROR, DEBUG
Inputs: query (required), level, regex, max_results, +1 more. Returns: result
summaryA
Get the AI-generated summary for a domain entry.
Args: domain: Domain (sessions, transcripts) id: File/directory name or unique prefix
Inputs: id (required), domain (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a distinct purpose: search for full-text search, list_domain for listing files, read for reading entries, summary for AI summaries, rebuild for index rebuilding, search_history for command history, and search_log for runtime log. No overlap exists.
Names use lowercase underscores, but the pattern is inconsistent: some are simple verbs (search, read, rebuild), one is a noun (summary), and three are verb_noun (list_domain, search_history, search_log). A more uniform verb_noun pattern would improve consistency.
With 7 tools, the server is well-scoped for its purpose of managing and querying history domains, command history, and logs. Each tool contributes meaningfully without redundancy.
The tool surface covers essential operations: search, list, read, and summarize across domains, plus separate search for history and log. Minor gaps like missing delete or create operations are acceptable for a viewer-oriented server.
Maintenance
Related MCP Connectors
Agent-driven search: build, import, tune, search, and score result quality — all over MCP.
Agent-to-agent messaging: directory, public lobby, DMs, channels, search. Stateless MCP + REST.
MCP server for searching Airweave collections with natural language queries.
Related MCP Servers
AlicenseBqualityDmaintenanceMCP server that turns any audio or video source into structured, searchable intelligence for agents, enabling download, transcription, semantic search, speaker identification, and more.226MIT- AlicenseAqualityDmaintenanceConfig-driven MCP server for cross-domain full-text search across agent session logs, meeting transcripts, and notification files.7MIT
- FlicenseNot gradedqualityDmaintenanceRead-only MCP server for Elasticsearch log querying. Enables natural language search, filtering, context retrieval, and aggregation of logs.-
- FlicenseNot gradedqualityBmaintenanceMCP server that indexes local Claude Code transcripts and provides keyword, phrase, semantic, and date-range search, plus full context/session recall.-