MCP.so
Sign In

Terminal History Mcp

@HasanJahidul

Repository

About Terminal History Mcp

terminal-history-mcp gives AI agents (Claude Code, Cursor, Cline, Zed, any MCP client) full-text search over your shell history.

#terminal#shell#history#zsh#bash#fish#sqlite#fts5#search#local-first#privacy#cli#developer-tools#memory#mcp

Basic information

Category

Developer Tools

Transports

stdio

Publisher

HasanJahidul

Submitted by

Jahidul Hasan

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "terminal-history": {
      "command": "npx",
      "args": [
        "-y",
        "terminal-history-mcp"
      ]
    }
  }
}

Tools

5

Re-parses the local shell history files (`~/.zsh_history`, `~/.bash_history`) and the hook's extended log into the SQLite index. Idempotent — already-indexed commands are skipped by hash, so it is safe to call repeatedly. Run it after a burst of shell activity to make recent commands searchable. Reads only local files; writes only to `~/.terminal-history-mcp/`. Takes no arguments. Returns counts of parsed / inserted / skipped entries.

Read-only. Full-text search (SQLite FTS5, stemmed, Unicode-aware) over all indexed shell commands. Supports keyword and prefix queries — e.g. `docker build`, `git reb*`. Returns the most recent matches first, each with timestamp, shell, cwd, and exit code when available. Local index only; nothing is sent anywhere. If a query returns nothing you may need `reindex` first.

Read-only. Lists the most recent commands that were run with a given working directory — answers "what was I doing in this project?". Requires the shell hook to have been installed (legacy entries have no cwd and won't appear). Returns newest first with timestamps and exit codes. Local index only.

Read-only. Lists recent commands that exited non-zero — a quick "what just broke?" feed. Optionally restrict to commands after a given epoch-millisecond timestamp. Requires the shell hook for exit-code capture (legacy entries have no exit code). Newest first. Local index only.

Read-only. For each command matching `query`, returns the commands run within a time window around it (default ±5 min) — surfacing multi-step sequences like `cd → npm run build → deploy`. Useful for reconstructing "how did I do X last time?". Returns up to `limit` chains, each a time-ordered list of command rows. Local index only.

Overview

What is Terminal History MCP?

Terminal History MCP lets AI coding agents search your local shell history (zsh, bash, fish) using SQLite FTS5 full‑text search. Commands are secret‑redacted before storage and never leave your machine.

How to use Terminal History MCP?

Install globally with npm, then run terminal-history-mcp index for a one‑time backfill and terminal-history-mcp install-hook to capture working directory, exit code, and duration. Alternatively, use zero‑install via npx by adding it to your mcpServers configuration. Tools available: reindex, search_history, recent_in_dir, failed_commands, command_chains.

Key features of Terminal History MCP

  • Local‑only SQLite FTS5 search of shell history
  • Supports zsh, bash, and fish shells
  • Secrets redacted before storage
  • Tools for search, recent commands, failures, chains
  • Idempotent reindex with hash dedupe
  • Zero network calls, fully offline

Use cases of Terminal History MCP

  • Recall long or forgotten commands from weeks ago
  • Investigate failed commands with non‑zero exit codes
  • Find commands run in a specific working directory
  • Get context windows around matching commands
  • Pair with localhost‑MCP for full dev environment memory

FAQ from Terminal History MCP

What shells does Terminal History MCP support?

It supports zsh, bash, and fish. All three have both history parsing and optional hook‑based capture for exit code, duration, and working directory.

How is privacy managed?

Data stays entirely local. Secrets are redacted before insertion using 11 ordered patterns (GitHub PATs, OpenAI keys, AWS keys, etc.). The database is at ~/.terminal-history-mcp/history.db.

Does Terminal History MCP require an internet connection?

No. It makes zero network calls and runs fully offline.

How do I install Terminal History MCP?

Install via npm install -g terminal-history-mcp, then index your history. Or skip installation by using npx -y terminal-history-mcp in your MCP client configuration.

What data is captured with the hook?

The optional hook captures the current working directory, exit code, and execution duration for each command, enriching the searchable history.

Comments

More Developer Tools MCP servers

Grafana MCP server

grafana

MCP server for Grafana

3.2K

Stakpak Agent CLI

stakpak

Ship your code, on autopilot. An open source agent that lives on your machines 24/7 and keeps your apps running. 🦀

1.6K

Smithery CLI

smithery-ai

Install, manage and develop MCP servers and skills for agents

788

Sentry

modelcontextprotocol

Model Context Protocol Servers

88.1K

Unity MCP (Server + Plugin)

IvanMurzak

AI Skills, MCP Tools, and CLI for Unity Engine. Full AI develop and test loop. Use cli for quick setup. Efficient token usage, advanced tools. Any C# method may be turned into a tool by a single line. Works with Claude Code, Gemini, Copilot, Cursor and any other absolutely for fr

3.5K