Terminal History MCP
terminal-history-mcp
Claude Code、Cline、Cursor、Zed、またはその他のMCPクライアントからシェル履歴(zsh / bash / fish)を検索します。ローカル専用。SQLite FTS5を使用。保存前にシークレットを削除します。

質問できること
"最後にステージングサーバーにsshしたのはいつ?"
"最近失敗したコマンドを表示して。"
"昨日
/etc/nginxで何を実行した?""3週間前に使った長い docker compose のフラグは何だった?"
"
kubectl apply前後のコマンドチェーンを表示して。"
Related MCP server: ClaudeX
インストール
npm install -g terminal-history-mcp
terminal-history-mcp index # one-time backfill from existing history(またはクローンから実行: git clone … && npm install && npm run build && npm link)
Claude Codeへの接続
claude mcp add --scope user terminal-history -- terminal-history-mcp
claude mcp list他のMCPクライアントへの接続
stdio MCPサーバー設定を受け入れる場所であればどこでも可能です:
{
"mcpServers": {
"terminal-history": {
"command": "terminal-history-mcp"
}
}
}MCPize経由で接続
ローカルインストールなしで、このMCPサーバーを即座に使用できます:
npx -y mcpize connect @HasanJahidul/terminal-history --client claudeまたはこちらから接続:https://mcpize.com/mcp/terminal-history
CWDと終了コードのキャプチャ(推奨)
デフォルトでは、zsh/bashの履歴ファイルにはコマンドのみが保存されます。recent_in_dir や failed_commands を有効にするには、シェルフックをインストールしてください:
terminal-history-mcp install-hook zsh # or bash, or fish
exec $SHELL # reloadこのフックは、パイプ区切りの行を ~/.terminal-history-mcp/extended.log に追記します。再インデックス時にこれらが読み込まれます。
スニペットを先に確認するには:
terminal-history-mcp print-hook zsh削除するには:
terminal-history-mcp uninstall-hook zshツール
ツール | 機能 |
| 全履歴に対するFTS5キーワードおよび前方一致検索 |
| 作業ディレクトリ内の直近N件のコマンド(フックが必要) |
| 終了コードが0以外のコマンド(フックが必要) |
| 各一致に対して、±5分以内のコマンドをリストアップ |
| 履歴ファイルと拡張ログを再解析 |
プライバシー
すべてローカルで完結します。データベースは ~/.terminal-history-mcp/history.db に保存されます。外部へのアップロードは一切ありません。
シークレットは挿入前にスクラブ(削除)されます。検出パターン:
GitHub PAT (
ghp_*,gho_*, …)OpenAIキー (
sk-*)Slackトークン (
xox[baprs]-*)AWSアクセスキー (
AKIA…)Authorization: Bearer/Basic <value>X-*-Token: …,X-*-Key: …,X-*-Secret: …ヘッダーTOKEN/KEY/SECRET/PASSWORD/API_KEYを含む環境変数CLIフラグ
--token=…,--api-key …,-k …URLの基本認証
https://user:pass@hostJWT (
eyJ.*.*)
漏洩を発見した場合は、Issueを作成してください。パターンをアップグレードした後にデータを消去して再インデックスするには:
rm ~/.terminal-history-mcp/history.db*
terminal-history-mcp index開発
git clone https://github.com/hasanjahidul/terminal-history-mcp
cd terminal-history-mcp
npm install
npm run build
npm testライセンス
MIT — LICENSE を参照してください。
Available Tools
7 toolsask_historyARead-onlyIdempotent
Read-only. Answers a natural-language question about your shell history, with citations (retrieval-augmented generation). Retrieves the top k entries with hybrid search, then, if TERMINAL_HISTORY_CHAT_MODEL is set, asks that chat model to answer only from those entries and cite them as [id:N]. Retrieved commands are passed as delimited untrusted data, never as instructions. Replies exactly "No relevant history found." when nothing retrieved is relevant. Without a chat model it returns the retrieved context only. Cited ids are checked against the retrieved set; any others are listed in invalid_citation_ids.
Inputs: question (required), k. Returns: note, answer, cited_ids, retrieved, +5 more
command_chainsARead-onlyIdempotent
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.
Inputs: query (required), limit, window_ms. Returns: count, chains
failed_commandsARead-onlyIdempotent
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.
Inputs: limit, since_ts_ms. Returns: count, results
recent_in_dirARead-onlyIdempotent
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.
Inputs: cwd (required), limit. Returns: count, results
reindexAIdempotent
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.
Inputs: no named parameters. Returns: parsed, skipped, inserted, ext_applied, +1 more
reindex_embeddingsAIdempotent
Builds the vector index behind search_history semantic/hybrid modes and ask_history. Embeds distinct indexed command texts (identical commands share one vector) that have no vector yet for the configured model, newest first, in batches of 64, via the OpenAI-compatible endpoint in TERMINAL_HISTORY_LLM_BASE_URL (default Ollama at http://localhost:11434/v1, model nomic-embed-text from TERMINAL_HISTORY_EMBED_MODEL). Non-localhost endpoints are refused unless TERMINAL_HISTORY_ALLOW_REMOTE_LLM=1. Sends only already-redacted text read from the local index. Changing the embedding model re-embeds everything for the new model. Run reindex first, then call until remaining is 0. Returns embedded / skipped / failed / remaining counts.
Inputs: limit. Returns: error, model, failed, skipped, +2 more
search_historyARead-onlyIdempotent
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. Default keyword mode is local index only; nothing is sent anywhere. semantic and hybrid modes embed only the query through the configured OpenAI-compatible endpoint (localhost Ollama by default) and need reindex_embeddings to have run. If a query returns nothing you may need reindex first.
Inputs: query (required), mode, limit. Returns: mode, count, results, keyword_error, +2 more
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 clearly distinct role: raw indexing, embedding indexing, keyword/semantic search, RAG-style Q&A, command-chain reconstruction, failure listing, and cwd-scoped recency listing. The two reindex tools are explicitly differentiated by their descriptions, and search_history vs. ask_history is cleanly separated as retrieval vs. natural-language answering.
Names are all snake_case and readable, but they mix verb_noun forms (search_history, ask_history), a bare verb (reindex), and noun/adjective phrases (command_chains, failed_commands, recent_in_dir). The pattern is not predictable from one tool to the next, though the names remain understandable.
Seven tools is well-scoped for a terminal-history server, covering indexing, search, semantic retrieval, and several targeted history views. Each tool has a clear reason to exist and none feels redundant or excessive.
The surface covers the core lifecycle: index raw history, build embeddings, search, ask questions, and inspect chains/failures/recent directory activity. Minor gaps exist, such as fetching a specific indexed command by id or managing/pruning the index, but these are not blocking for the stated purpose.
Maintenance
Related MCP Connectors
One searchable history across every AI coding tool, with secret scanning and a shared task board.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA powerful tool for exploring, searching, and managing your shell command history through the MCP (Model Control Protocol) interface. This project allows you to easily access, search, and retrieve your previously executed shell commands.2MIT
- AlicenseAqualityDmaintenancePersistent memory + FTS5 full-text search for Claude Code conversation history. Indexes ~/.claude/projects/ JSONL into SQLite, exposes 10 MCP tools (store/recall/search memories, browse sessions, get summaries) plus prompts. Includes a web UI for visual exploration10106 npm98MIT
- AlicenseAqualityDmaintenanceInspect, manage, and kill local dev servers via MCP. Stop guessing what's on :3000. Five tools: list servers with framework detection, inspect ports, find zombies, diagnose conflicts, safe-kill with dry-run default. Local, no cloud, no telemetry.510 npm4MIT
- AlicenseAqualityDmaintenanceSemantic git queries via MCP. Beyond git log — answer who/what/why about any line, file, or branch with blame, co-change, PR linkage.67 npm2MIT