English Français العربية

Terminal History MCP

Community Developer tools

Local full-text search over zsh, bash and fish history, with secret redaction and optional capture of cwd, exit code and duration.

Source code Documentation

What can you do with Terminal History MCP?

  • "When did I last ssh into the staging server?"
  • "Show recent failed commands."
  • "What did I run yesterday in /etc/nginx?"
  • "What's that long docker compose flag I used 3 weeks ago?"
  • "Show command chains around kubectl apply."

Install

The installation steps are in the documentation below. Documentation

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. terminal-history-mcp
  2. What you can ask
  3. Install
  4. Connect via MCPize
  5. Capture cwd + exit code (recommended)
  6. Tools
  7. Privacy
  8. Development
  9. License

terminal-history-mcp

Search your shell history (zsh / bash / fish) from Claude Code, Cline, Cursor, Zed, or any MCP client. Local-only. SQLite FTS5. Secret-redacted before storage.

What you can ask

  • "When did I last ssh into the staging server?"
  • "Show recent failed commands."
  • "What did I run yesterday in /etc/nginx?"
  • "What's that long docker compose flag I used 3 weeks ago?"
  • "Show command chains around kubectl apply."

Install

npm install -g terminal-history-mcp
terminal-history-mcp index           # one-time backfill from existing history

(Or run from a clone: git clone … && npm install && npm run build && npm link.)

Wire to Claude Code
claude mcp add --scope user terminal-history -- terminal-history-mcp
claude mcp list
Wire to other MCP clients

Anywhere that takes a stdio MCP server config:

{
  "mcpServers": {
    "terminal-history": {
      "command": "terminal-history-mcp"
    }
  }
}

Connect via MCPize

Use this MCP server instantly with no local installation:

npx -y mcpize connect @HasanJahidul/terminal-history --client claude

Or connect at: **https://mcpize.com/mcp/terminal-history**

By default zsh/bash history files store only the command. To unlock recent_in_dir and failed_commands, install the shell hook:

terminal-history-mcp install-hook zsh    # or bash, or fish
exec $SHELL                              # reload

The hook appends pipe-delimited lines to ~/.terminal-history-mcp/extended.log. Reindex picks them up.

To inspect the snippet first:

terminal-history-mcp print-hook zsh

To remove:

terminal-history-mcp uninstall-hook zsh

Tools

ToolWhat it does
search_history(query, limit)FTS5 keyword + prefix match across all history
recent_in_dir(cwd, limit)Last N commands in a working dir (needs hook)
failed_commands(since_ts_ms, limit)Commands with non-zero exit (needs hook)
command_chains(query, window_ms, limit)For each match, list commands within ±5 min
reindexRe-parse history files + extended log

Privacy

Everything is local. The DB lives at ~/.terminal-history-mcp/history.db. Nothing is uploaded.

Secrets are scrubbed before insert. Detected patterns:

  • GitHub PATs (ghp_*, gho_*, …)
  • OpenAI keys (sk-*)
  • Slack tokens (xox[baprs]-*)
  • AWS access keys (AKIA…)
  • Authorization: Bearer/Basic <value>
  • X-*-Token: …, X-*-Key: …, X-*-Secret: … headers
  • Env vars containing TOKEN / KEY / SECRET / PASSWORD / API_KEY
  • CLI flags --token=…, --api-key …, -k …
  • URL basic-auth https://user:pass@host
  • JWTs (eyJ.*.*)

If you find a leak, please open an issue. To wipe and re-index after upgrading patterns:

rm ~/.terminal-history-mcp/history.db*
terminal-history-mcp index

Development

git clone https://github.com/hasanjahidul/terminal-history-mcp
cd terminal-history-mcp
npm install
npm run build
npm test

License

MIT — see LICENSE.

Frequently asked questions

What is Terminal History MCP?

Local full-text search over zsh, bash and fish history, with secret redaction and optional capture of cwd, exit code and duration.

How do I install Terminal History MCP?

Follow the installation steps in its documentation, shown on this page and in its repository.

Is Terminal History MCP open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Terminal History MCP?

It is published by HasanJahidul. AI.tn lists it but does not maintain or endorse it.

From the community awesome-mcp-servers lists and the project's GitHub repository. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.