OpenCode History MCP server
Commit Oct 31, 2026Lets AI coding agents search local OpenCode conversation history to avoid repeating past work or re-diagnosing solved bugs.
Also known as singleflo/opencode-history-mcp
- Stars
- 4
- Tools
- 7
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 31, 2026
- License
- MIT
What is OpenCode History MCP?
OpenCode History lets AI coding agents search local OpenCode conversation history to avoid repeating past work or re-diagnosing solved bugs. It exposes 7 tools, such as search_history, find_related_work, find_sessions_by_file.
Summary generated from the project's README
About OpenCode History MCP server
Searching through past OpenCode conversations to prevent AI agents from repeating mistakes or re-diagnosing solved bugs is the primary function of this local MCP server. It allows developers to connect their coding agents to their existing OpenCode SQLite database, providing a way to retrieve context from previous bug fixes, feature implementations, and diagnostic sessions. The server builds a private full-text search index using FTS5 to ensure queries are fast and efficient without needing to scan large JSON blobs manually.
Everything runs entirely on your local machine, ensuring that no data ever leaves your computer. It is designed for use with MCP clients like Claude Desktop, Cursor, or Hermes Agent. Users can manage their data by building an initial index or using the auto-sync feature that updates the index every five minutes. The server supports OpenCode v2 through version 0.2.0 and above, and it can be configured via the OPENCODE_DATA_DIR environment variable to handle custom data paths or WSL setups.
What you can do with it
- 1Preventing redundant bug diagnosisAn AI agent can check if a specific bug or error has been addressed in a previous session to avoid wasting time.
- 2Finding work related to specific filesA developer can ask an agent to identify every past session that involved modifying or mentioning a particular file.
Written from the project's README. Every use case is checked against a quote from it.
OpenCode History MCP tools 7
Detected from the READMEsearch_historyfind_related_workfind_sessions_by_filelist_sessionsget_session_detailget_session_messagesget_stats
| search_history | — | |
| find_related_work | — | |
| find_sessions_by_file | — | |
| list_sessions | — | |
| get_session_detail | — | |
| get_session_messages | — | |
| get_stats | — |
Configuration
OPENCODE_DATA_DIR
| Name | Description | |
|---|---|---|
| OPENCODE_DATA_DIR | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesingleflo/opencode-history-mcp is public and reachablegithub.com/singleflo/opencode-history-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-31github.com/singleflo/opencode-history-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model7 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubOpenCode History MCP
A local MCP (Model Context Protocol) server that lets AI coding agents search your past OpenCode conversations — before they start exploring files or re-doing work you already did.
Everything runs on your machine: it reads OpenCode's own SQLite database and builds a private full-text search index next to it. No network calls, no external services, no data ever leaves your computer.
If this saves you from re-diagnosing the same bug twice, consider dropping a ⭐ — it helps other OpenCode users find it too.
Why
If you use OpenCode daily across many projects,
you build up thousands of past sessions — bug fixes, feature work,
diagnostics — sitting untapped in opencode.db. When you start a new
session on the same module or file, your agent has no idea any of that
happened. It re-explores from scratch, or worse, repeats a mistake you
already fixed three weeks ago.
This server exposes that history as MCP tools any agent can call: "has this file been touched before? what did we conclude last time? what related work exists in this project?"
How it works
OpenCode's own DB (read-only) Our derived index (read-write)
┌─────────────────────────┐ ┌──────────────────────────┐
│ opencode.db │ builds → │ opencode-history.db │
│ - session_v2 / │ │ - sessions (denormalized) │
│ session_message │ │ │
│ - JSON blobs per row │ │ - search_idx (FTS5) │
└─────────────────────────┘ │ - session_files (index) │
└──────────────────────────┘
- Source DB stays untouched. We open it
mode=ro(read-only, WAL-aware) and never write to it. - A separate FTS5 index holds denormalized session metadata + full-text search over user/assistant text — orders of magnitude faster than scanning JSON blobs on every query.
- Auto-sync on startup, TTL-cached (5 min): if OpenCode wrote new sessions since the last check, the index catches up incrementally before serving results.
- Privacy is structural, not a policy: the index lives next to OpenCode's own DB, on your machine, under your OS user. There is no hosted/shared version of this server — everyone runs their own, against their own history.
Compatibility
| OpenCode | opencode-history-mcp |
|---|---|
v1 (tables session / message / part) |
uvx opencode-history-mcp==0.1.0 |
v2 (tables session_v2 / session_message / session_part) |
>= 0.2.0 |
From 0.2.0 only OpenCode v2 is supported. On a v1 database the indexer and the server stop with an error pointing to 0.1.0. OpenCode v2 migrates a v1 database on first start, after which 0.2.0 works on it.
Quickstart
1. Build the index (first run)
uvx opencode-history-mcp --build-index
This reads your local opencode.db and builds opencode-history.db
next to it. Takes a few seconds per thousand sessions.
2. Add it to your MCP client
hermes mcp add history \
--command uvx \
--args opencode-history-mcp
Or in ~/.hermes/config.yaml:
mcp_servers:
history:
command: uvx
args:
- opencode-history-mcp
enabled: true
In ~/.config/opencode/opencode.jsonc (global) or .opencode/opencode.jsonc
(project):
{
"mcp": {
"history": {
"type": "local",
"command": ["uvx", "opencode-history-mcp"],
"enabled": true
}
}
}
In claude_desktop_config.json:
{
"mcpServers": {
"opencode-history": {
"command": "uvx",
"args": ["opencode-history-mcp"]
}
}
}
Any client that supports local stdio MCP servers works the same way — point it at:
command: uvx
args: ["opencode-history-mcp"]
3. Keep the index fresh (optional)
The server auto-syncs on startup (checked every 5 minutes per session). For a fully up-to-date index without waiting on that check, run:
uvx opencode-history-mcp --sync-index
You can schedule this with cron/launchd if you want the index always warm ahead of time.
Tools
| Tool | Purpose |
|---|---|
search_history |
Full-text search (FTS5) over user prompts and assistant responses. Ranked by relevance + recency + activity. |
find_related_work |
Higher-precision match on session titles and original task descriptions. Best first call for "have we done this before?" |
find_sessions_by_file |
Find every session that modified or mentioned a specific file. |
list_sessions |
Browse sessions in a directory, sorted by date/messages/cost/tokens. |
get_session_detail |
Full metadata for one session: task, files touched, cost, tokens, sub-agent count. |
get_session_messages |
Read the actual paginated message history of a session. |
get_stats |
Aggregate stats: session/message counts, cost, time range, activity distribution. |
All tools accept an optional directory parameter to scope results to
one project. Recommended pattern: search scoped to the current
project first; if nothing relevant comes back, retry without
directory for a global search — related work sometimes lives in a
sibling project.
Cross-platform paths
The server resolves OpenCode's data directory the same way OpenCode
itself does (its xdg-basedir-based resolution — see
packages/core/src/global.ts
in the OpenCode source):
| Platform | Default path | Notes |
|---|---|---|
| Linux | $XDG_DATA_HOME/opencode → falls back to ~/.local/share/opencode |
Standard XDG Base Directory behavior. |
| macOS | ~/.local/share/opencode |
⚠️ Not ~/Library/Application Support/opencode. OpenCode has no macOS-specific branch in its path resolution — it uses the same XDG-style path as Linux. This trips people up who assume Apple conventions apply. |
| Windows | %LOCALAPPDATA%\opencode |
Falls back to %USERPROFILE%\AppData\Local\opencode if the env var is unset. |
| WSL (WSL2/WSL1) | Same as Linux — ~/.local/share/opencode |
WSL runs a real Linux kernel, so sys.platform reports "linux" and the Linux path applies automatically. This is only correct if OpenCode itself runs inside WSL. |
The WSL + Windows-side-OpenCode edge case
If you installed OpenCode on Windows natively (not inside WSL) but
run your MCP client or terminal inside WSL, the database lives on
the Windows filesystem, which WSL mounts under /mnt/c/.... The
automatic Linux-path resolution will look in the wrong place (your
WSL home directory, not the Windows one) and won't find it.
Fix: point the server explicitly at the mounted Windows path via the
OPENCODE_DATA_DIR environment variable:
export OPENCODE_DATA_DIR="/mnt/c/Users/<your-windows-username>/AppData/Local/opencode"
Or set it in your MCP client's env config for this server, e.g. for
Hermes:
mcp_servers:
history:
command: uvx
args:
- opencode-history-mcp
env:
OPENCODE_DATA_DIR: /mnt/c/Users/yourname/AppData/Local/opencode
enabled: true
Any other custom setup
OPENCODE_DATA_DIR always wins over auto-detection, on every platform
— use it whenever OpenCode's data lives somewhere non-standard (custom
XDG_DATA_HOME, a container, a synced/mounted drive, etc).
Teaching your agent to use this automatically
Having the tools available isn't enough — agents default to exploring
files directly unless told otherwise. Add this to your project's
AGENTS.md (OpenCode) or CLAUDE.md (Claude Code) to make history
search a mandatory first step:
## Check history before starting work
Before exploring files or writing code for any task that touches an
existing module, file, or bug, call the history search tools first:
1. `find_related_work(query="<short description of the task>")` —
has this exact task been worked on before?
2. If the task names a specific file, also call
`find_sessions_by_file(file_path="...")`.
3. If step 1 returns nothing relevant, broaden with
`search_history(query="...")` (full-text, no directory scope).
Only start exploring the codebase directly if history search comes up
empty. If a relevant past session is found, read it with
`get_session_detail` / `get_session_messages` before proceeding —
don't repeat work or re-diagnose an issue that was already solved.
This is a strong nudge, not a hard constraint — the agent can still decide history search isn't relevant for a truly new task. The goal is making "check first" the default reflex instead of an afterthought.
Development
git clone https://github.com/singleflo/opencode-history-mcp.git
cd opencode-history-mcp
uv venv
uv pip install -e .
# Build the index against your own OpenCode history
python -m opencode_history_mcp.build_index --full
# Run the server directly (stdio)
python -m opencode_history_mcp.server
# Inspect with the FastMCP dev tools
fastmcp dev -m opencode_history_mcp.server
See docs/design.md for the full design rationale
(ranking formula, schema decisions, sync algorithm).
Contributing
Issues and PRs welcome. If you hit a platform-specific path issue,
please include your OS, OPENCODE_DATA_DIR (if set), and the actual
location of your opencode.db — that's the fastest way to fix an edge
case in the resolution logic.
License
MIT — see LICENSE.
OpenCode History MCP questions
What tools does OpenCode History MCP provide?
It exposes 7 tools, including search_history, find_related_work, find_sessions_by_file, list_sessions, get_session_detail.
Is my data safe with this server?
Yes, everything runs locally on your machine and no data ever leaves your computer.
Does this server modify my existing OpenCode database?
No, the source database is opened in read-only mode and remains untouched.
What if my OpenCode data is in a non-standard location?
You can explicitly point the server to your data directory by setting the OPENCODE_DATA_DIR environment variable.