How to Search Terminal History Using MCP: A Complete Guide

Model Context Protocol (MCP) enables AI agents to search your shell history by connecting to a local MCP server that indexes bash, zsh, and fish commands in a SQLite FTS5 database and exposes semantic search tools via JSON-RPC endpoints.

Searching through weeks of terminal commands to find that specific docker compose configuration or debugging script is a common frustration for developers. The Model Context Protocol (MCP) solves this by allowing AI assistants to query your local shell history as a structured database. According to the punkpeye/awesome-mcp-servers repository (specifically at line 734 of the README), the reference implementation HasanJahidul/terminal-history-mcp provides a local-only Python server that captures every command—including working directory, exit status, and execution duration—and indexes them for full-text search.

Understanding the MCP Terminal History Server

The terminal-history-mcp server bridges your shell history with AI agents through the Model Context Protocol. Unlike cloud-based solutions, this implementation stores data entirely locally in a SQLite database with FTS5 (Full Text Search) capabilities.

Core Architecture

When active, the server captures command metadata through a shell hook and stores it in ~/.local/share/terminal-history-mcp/history.db. The SQLite FTS5 extension enables fast full-text queries across your entire command history without exposing sensitive data to external APIs. As documented in the punkpeye/awesome-mcp-servers listing, all secrets are automatically redacted before any data returns to the model.

Available Search Tools

The server exposes five primary tools through JSON-RPC endpoints:

• search_history: Executes full-text search across all recorded commands using SQLite FTS5 syntax.
• recent_in_dir: Filters commands by the directory in which they were executed.
• failed_commands: Retrieves recent commands that exited with non-zero status codes for debugging purposes.
• command_chains: Identifies sequences of commands that frequently appear together in your workflow.
• reindex: Rebuilds the FTS5 index after configuration changes or database maintenance.

Installation and Setup

Setting up the terminal history search requires installing the Python package, configuring your shell environment, and launching the MCP server.

Installing the Python Package

The server is distributed via PyPI and requires no API keys or remote authentication. Install it using pip:

pip install terminal-history-mcp

This command installs both the MCP server daemon and the mcp-cli helper utility used for direct queries.

Configuring the Shell Hook

To capture commands automatically, add the shell hook to your startup configuration. The hook supports bash, zsh, and fish shells.

For bash or zsh, append this line to ~/.bashrc or ~/.zshrc:

eval "$(terminal-history-mcp --hook)"

For fish shell, add to ~/.config/fish/config.fish:

eval (terminal-history-mcp --hook)

After sourcing the file (e.g., source ~/.bashrc), every command you execute will be logged with its working directory, exit code, and duration to the local SQLite database.

Starting the MCP Server

Launch the server to expose the JSON-RPC endpoint. By default, it listens on localhost to ensure security:

terminal-history-mcp --port 3001 &

The server is now accessible at http://127.0.0.1:3001/mcp and ready to accept tool invocations from MCP-compatible clients like Claude Desktop or Cursor AI.

Querying Terminal History

Once the server is running, you can search your shell history through multiple interfaces: AI clients, direct HTTP requests, or the built-in CLI.

Full-Text Search with search_history

The search_history tool performs FTS5 queries against your command database. From the command line, use the mcp-cli helper:

mcp-cli search_history "docker compose up"

This returns matching commands with timestamps, working directories, and exit codes. For programmatic access, send a JSON-RPC POST request:

POST http://127.0.0.1:3001/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "search_history",
  "params": {
    "query": "git commit -m"
  }
}

The response includes all matching entries, enabling AI agents to understand your previous Git workflows or deployment patterns.

Debugging with failed_commands

To review recent errors without scrolling through terminal buffers, query the failed_commands tool:

mcp-cli failed_commands --limit 5

This retrieves the last five commands that exited with non-zero status, including the directory context where they failed. This is particularly useful when an AI assistant needs to understand what went wrong in your last deployment attempt.

Contextual Directory Search

The recent_in_dir tool filters history by working directory. This helps AI assistants understand project-specific workflows:

mcp-cli recent_in_dir "/path/to/project"

When integrated with Claude Desktop or Cursor AI, these tools allow the model to suggest commands based on what you typically run in specific directories.

Integration with MCP Clients

MCP-compatible AI assistants connect to your local terminal history through the http://127.0.0.1:3001/mcp endpoint. Configure your client to use this local server, and the AI gains the ability to search your shell history using natural language queries that translate into the structured tool calls described above.

Summary

• Local-First Architecture: The terminal-history-mcp server stores data in ~/.local/share/terminal-history-mcp/history.db using SQLite FTS5, ensuring privacy and fast full-text search.
• Automatic Capture: A shell hook integration records commands with metadata (cwd, exit code, duration) for bash, zsh, and fish.
• Five Search Tools: The server exposes search_history, recent_in_dir, failed_commands, command_chains, and reindex via JSON-RPC at http://127.0.0.1:3001/mcp.
• Security Features: Secrets and sensitive tokens are automatically redacted before data reaches the AI model.
• Multiple Interfaces: Query via mcp-cli, direct HTTP POST requests, or integrate with Claude Desktop and Cursor AI.

Frequently Asked Questions

What shell environments are supported?

The terminal-history-mcp hook supports bash, zsh, and fish shells. You configure it by adding eval "$(terminal-history-mcp --hook)" to your respective shell configuration file (~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish). After sourcing the configuration, the hook automatically captures every command along with its working directory and exit status.

How does the server handle sensitive data like passwords?

According to the implementation details referenced in punkpeye/awesome-mcp-servers, the server includes automatic secret redaction functionality. Before any command data is returned to the AI model through the MCP interface, passwords, API keys, and other sensitive tokens are filtered out. This ensures that your local credentials remain secure even when sharing command history with AI assistants.

Can I use this without an AI assistant?

Yes. While designed for MCP integration, the package includes the mcp-cli command-line tool that communicates directly with the local server. You can run searches like mcp-cli search_history "npm install" or mcp-cli failed_commands without connecting Claude, Cursor, or any other AI client. The server responds to standard JSON-RPC requests, making it accessible from any HTTP client or script.

Where is the history database stored?

The SQLite database containing your indexed command history is stored at ~/.local/share/terminal-history-mcp/history.db. This location follows the XDG Base Directory Specification. The database uses SQLite FTS5 for full-text search capabilities and contains tables for commands, working directories, exit codes, and execution timestamps.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}