Skip to main content
Glama
Terminal History MCP

Terminal History MCP

by HasanJahidul

terminal-history-mcp

MCPize mcp.so CI npm version License: MIT

Claude Code, Cline, Cursor, Zed 또는 모든 MCP 클라이언트에서 셸 기록(zsh / bash / fish)을 검색하세요. 로컬 전용입니다. SQLite FTS5를 사용합니다. 저장 전에 비밀 정보가 삭제됩니다.

demo

질문 예시

  • "마지막으로 스테이징 서버에 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

도구

도구

기능

search_history(query, limit)

모든 기록에 걸쳐 FTS5 키워드 + 접두사 일치 검색

recent_in_dir(cwd, limit)

작업 디렉토리 내 최근 N개 명령어 (훅 필요)

failed_commands(since_ts_ms, limit)

0이 아닌 종료 코드를 가진 명령어 (훅 필요)

command_chains(query, window_ms, limit)

각 일치 항목에 대해 ±5분 이내의 명령어 나열

reindex

기록 파일 + 확장 로그 재파싱

개인정보 보호

모든 데이터는 로컬에 저장됩니다. DB는 ~/.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@host

  • JWT (eyJ.*.*)

유출을 발견하면 이슈를 열어주세요. 패턴 업그레이드 후 데이터를 삭제하고 재색인하려면:

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 tools
ask_historyA
Read-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_chainsA
Read-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_commandsA
Read-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_dirA
Read-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

reindexA
Idempotent

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_embeddingsA
Idempotent

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_historyA
Read-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

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Persistent 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 exploration
      10
      106 npm
      98
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Inspect, 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.
      5
      10 npm
      4
      MIT