Opencode Session Context

osc-mcp

Demo

https://github.com/user-attachments/assets/d41fb2b8-96ca-4a03-9bcd-afede68212e2

Dictionary

• Description
• How It Works
• Tools
• Requirements
• Install
• Run
• Tips
• Environment
• OS Notes

Description

opencode-session-context-mcp (aka osc-mcp) is an MCP server that supplies new sessions with context from prior sessions in the same project, so your OpenCode instance can pick up where you left off and better align with your project’s ongoing needs.

⚠️ Caution: this tool is under active development, especially around optimizing token spend when fetching context. Contributions are welcome.

How It Works

• On session start, the server stores a filtered summary of the previous session into mcp.db.
• When a new session asks for context, it looks up recent summaries for the current project.
• The client (OpenCode) uses those summaries to seed your new session with relevant context.

Tools

• store_previous_session_content: stores filtered content from the most recent previous session into mcp.db.
• get_relevant_sessions: returns a lightweight list of recent session summaries for the current project.

Requirements

• bun
• git
• OpenCode (installed and configured)

Install

Quick Start (best UX)

Linux/mac

curl -fsSL https://github.com/vohs-1980/osc-mcp/blob/main/scripts/install.sh?raw=1 | bash

Windows (PowerShell):

irm https://github.com/vohs-1980/osc-mcp/blob/main/scripts/install.ps1?raw=1 | iex

Security note: review scripts/install.sh before running or use the manual steps below. For Windows, review scripts/install.ps1 before running.

What the installer does (Linux/mac):

• Finds your opencode.json (honors XDG_CONFIG_HOME).
• Verifies bun and git are installed.
• Verifies the OpenCode data dir exists (honors XDG_DATA_HOME).
• Clones or updates the repo in ~/.local/share/opencode/osc-mcp.
• Runs bun install and builds the server.
• Updates opencode.json to add the "osc-mcp" MCP entry.
• If config editing fails or --no-config is set, prints manual steps.

If your config is invalid JSON or you pass --no-config, follow the manual steps below.

Manual Install

git clone https://github.com/vohs-1980/osc-mcp.git \
  ~/.local/share/opencode/osc-mcp
cd ~/.local/share/opencode/osc-mcp
bun install
bun run build

OpenCode config (~/.config/opencode/opencode.json):

If you don't already have the instruction files listed, add them:

"instructions": [
  "~/.local/share/opencode/osc-mcp/instructions/session-start.md",
  "~/.local/share/opencode/osc-mcp/instructions/context-lookup.md"
]

Then add the local MCP entry (if not present):

"osc-mcp": {
  "type": "local",
  "enabled": true,
  "command": ["bun", "~/.local/share/opencode/osc-mcp/src/index.ts"]
}

Run

# Run the MCP server
bun src/index.ts

Tips

• Start OpenCode from your project root so the MCP can map sessions to the correct project.
• Keep your project in git so sessions can be tied to a stable repo context.

Environment

• OPENCODE_DB: Path to OpenCode DB (default ~/.local/share/opencode/opencode.db)

If the default path doesn’t work for your setup, set it explicitly before launching OpenCode/MCP.

Example:

export OPENCODE_DB="$HOME/.local/share/opencode/opencode.db"
opencode

Installer overrides (optional):

• OSC_MCP_REPO_URL: Git repo URL to clone (default https://github.com/vohs-1980/osc-mcp.git).
• OSC_MCP_INSTALL_DIR: Install directory (default ~/.local/share/opencode/osc-mcp).
• OSC_MCP_REF: Git ref to checkout (tag/branch/commit, default main).
• XDG_CONFIG_HOME: Base config directory (default ~/.config).
• XDG_DATA_HOME: Base data directory (default ~/.local/share).

Example override:

export OSC_MCP_REPO_URL="https://github.com/vohs-1980/osc-mcp.git"
export OSC_MCP_INSTALL_DIR="$HOME/.local/share/opencode/osc-mcp"
export OSC_MCP_REF="v0.1.0"
export XDG_CONFIG_HOME="$HOME/.config"
export XDG_DATA_HOME="$HOME/.local/share"

OS Notes

• macOS/Linux: use scripts/install.sh (requires bash, git, bun)
• Windows: use scripts/install.ps1 in PowerShell.

Config path detection (installers search in this order):

macOS/Linux:

1. $XDG_CONFIG_HOME/opencode/opencode.json
2. ~/.config/opencode/opencode.json
3. ~/Library/Application Support/opencode/opencode.json

Windows:

1. %XDG_CONFIG_HOME%\opencode\opencode.json
2. %APPDATA%\opencode\opencode.json
3. %LOCALAPPDATA%\opencode\opencode.json
4. ~\.config\opencode\opencode.json
5. ~\Library\Application Support\opencode\opencode.json

Default data locations (databases):

macOS/Linux:

• ~/.local/share/opencode/opencode.db
• ~/.local/share/opencode/osc-mcp/mcp.db

Windows:

• %USERPROFILE%\.local\share\opencode\opencode.db
• %USERPROFILE%\.local\share\opencode\osc-mcp\mcp.db

License

MIT. See LICENSE.