threadctx MCP server
✓ VerifiedProvides shared memory for AI coding agents to store and retrieve architectural decisions and project context across local and team environments.
Also known as threadctx-dev/threadctx-mcp
- Stars
- 1
- Tools
- 2
- Downloads, 30 days
- —
- Latest version
- 0.5.0
- Last commit
- Jul 29, 2026
- License
- MIT
What is threadctx MCP?
threadctx provides shared memory for AI coding agents to store and retrieve architectural decisions and project context across local and team environments. It exposes 2 tools, such as memory_write, memory_query.
Summary generated from the project's README
About threadctx MCP server
threadctx-mcp provides a shared memory layer for AI coding agents to store and retrieve architectural decisions and project context. It is designed for developers using clients like Claude Code, Cursor, Windsurf, and GitHub Copilot. The server operates in two modes: a local mode that stores data in a plain JSON file at ~/.threadctx/local.json with no network calls, and a cloud mode for team-wide semantic search that requires an API key from threadctx.dev.
Users can initialize a repository for a team using the init command, which creates configuration files for different MCP clients. The server automatically manages agent rule files like AGENTS.md and CLAUDE.md to ensure models proactively use memory_query and memory_write tools. For teams wanting to automate context gathering, the capture command can distill git history into reusable memories using a developer's own LLM provider key.
What you can do with it
- 1Automate context extraction from git historyYou can turn recent code commits into structured memory by running a capture command that uses your LLM provider.
- 2Ensure agents follow memory protocolsThe server automatically injects instructions into rule files so agents know to query memory before starting tasks.
- 3Maintain local-only project contextDevelopers can store project-specific knowledge on their own machine without any external network dependencies.
Written from the project's README. Every use case is checked against a quote from it.
How to install threadctx MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall threadctx MCP in Claude Code
$ claude mcp add --env 'THREADCTX_API_KEY=<YOUR_THREADCTX_API_KEY>' threadctx-mcp -- npx -y threadctx-mcpInstall threadctx MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"threadctx-mcp": {
"command": "npx",
"args": [
"-y",
"threadctx-mcp"
],
"env": {
"THREADCTX_API_KEY": "<YOUR_THREADCTX_API_KEY>"
}
}
}
}Install threadctx MCP in VS Code
.vscode/mcp.json
{
"servers": {
"threadctx-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"threadctx-mcp"
],
"env": {
"THREADCTX_API_KEY": "<YOUR_THREADCTX_API_KEY>"
}
}
}
}Install threadctx MCP in VS Code CLI
$ code --add-mcp '{"name":"threadctx-mcp","type":"stdio","command":"npx","args":["-y","threadctx-mcp"],"env":{"THREADCTX_API_KEY":"<YOUR_THREADCTX_API_KEY>"}}'Install threadctx MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"threadctx-mcp": {
"command": "npx",
"args": [
"-y",
"threadctx-mcp"
],
"env": {
"THREADCTX_API_KEY": "<YOUR_THREADCTX_API_KEY>"
}
}
}
}Install threadctx MCP in Codex
$ codex mcp add threadctx-mcp --env 'THREADCTX_API_KEY=<YOUR_THREADCTX_API_KEY>' -- npx -y threadctx-mcpInstall threadctx MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.threadctx-mcp] command = "npx" args = ["-y", "threadctx-mcp"] [mcp_servers.threadctx-mcp.env] THREADCTX_API_KEY = "<YOUR_THREADCTX_API_KEY>"
Install threadctx MCP in Gemini CLI
$ gemini mcp add -s user -e 'THREADCTX_API_KEY=<YOUR_THREADCTX_API_KEY>' threadctx-mcp npx -- -y threadctx-mcpInstall threadctx MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"threadctx-mcp": {
"command": "npx",
"args": [
"-y",
"threadctx-mcp"
],
"env": {
"THREADCTX_API_KEY": "<YOUR_THREADCTX_API_KEY>"
}
}
}
}threadctx MCP tools 2
Detected from the READMEmemory_writememory_query
| memory_write | — | |
| memory_query | — |
Configuration
THREADCTX_API_KEYSecretAPI key for cloud mode, issued at threadctx.dev. Not needed in local mode.
ANTHROPIC_API_KEYTHREADCTX_CAPTURE_ENABLEDTHREADCTX_MODE'local' (default, free, no signup) or 'cloud' (shared team memory)
| Name | Description | |
|---|---|---|
| THREADCTX_API_KEY | API key for cloud mode, issued at threadctx.dev. Not needed in local mode. | Secret |
| ANTHROPIC_API_KEY | — | |
| THREADCTX_CAPTURE_ENABLED | — | |
| THREADCTX_MODE | 'local' (default, free, no signup) or 'cloud' (shared team memory) |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablethreadctx-dev/threadctx-mcp is public and reachablegithub.com/threadctx-dev/threadctx-mcp ↗Pass
- Package names this repository as its sourcethreadctx-mcp names threadctx-dev/threadctx-mcp as sourcenpmjs.com/package/threadctx-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-07-29github.com/threadctx-dev/threadctx-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from threadctx-mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model2 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 GitHubthreadctx-mcp
Shared memory MCP server for AI coding agents. Works identically with
Claude Code, Cursor, and any MCP client — same package, same config
shape, no per-client integration work. On first start it also drops a
"check team memory" instruction into whichever agents' rule files your repo
uses (AGENTS.md, CLAUDE.md, Copilot, Windsurf, Cline, Gemini) so the
memory actually gets read, not just exposed.
This repo runs on itself: its own
AGENTS.mdandCLAUDE.mdwere set up withnpx threadctx-mcp init, the same command you'd run — check the git history if you want to see it happen.
Modes
- Local (default, free, no signup): memory stored as a plain JSON file
at
~/.threadctx/local.json— zero native dependencies, sonpx threadctx-mcpinstalls instantly on any machine with Node 18+ (no compiler, no node-gyp step). No network calls except to whichever LLM provider your agent already uses. Matching is keyword-based, scoped to the current repo (detected viagit remote). Runnpx threadctx-mcp listany time to see exactly what your agents have stored. - Cloud (paid Team tier+): memory shared across everyone on the repo,
with real semantic search. Requires an API key from
threadctx.dev (or your own self-hosted
deployment — see
../cloud/README.md).
Quick start
# Local mode — nothing to configure. Also auto-adds the "check team memory"
# instruction to your agents' rule files (AGENTS.md, CLAUDE.md, and any
# detected tool-specific files) on first start.
npx threadctx-mcp
# Set a repo up for your whole team (run once, commit the results)
npx threadctx-mcp init
# Cloud mode — shared team memory via threadctx.dev
npx threadctx-mcp init --mode=cloud --api-key=tctx_xxx
# Joining a repo a teammate already set up? One command:
npx threadctx-mcp join
# See what your agents have written to this machine
npx threadctx-mcp list # this repo
npx threadctx-mcp list --all # every repo
init writes three committable, secret-free files: .threadctx.json
(just { "mode": ... }), .mcp.json (Claude Code project config), and
.cursor/mcp.json (Cursor project config). Commit all three — every
teammate who then opens the repo in Claude Code or Cursor is prompted to
enable threadctx automatically, with nothing to install or configure.
Teammates on other MCP clients run npx threadctx-mcp join, which sets up
their machine the same way and prints the config block for their client.
Your API key never appears in any committed file. It is read from the
THREADCTX_API_KEY environment variable at runtime (export it in your
shell profile), so secrets stay out of version control by construction.
threadctx also adds a small, clearly-marked instruction to your project
rules telling the agent to call memory_query before a task and
memory_write after. It writes the two universal files every time —
AGENTS.md (the cross-tool standard read by Copilot,
Cursor, Windsurf, Zed, Codex, Aider, and ~24 others) and CLAUDE.md
(Claude Code's richer native format) — plus .cursor/rules/threadctx.mdc.
It then adds a tool-specific file only when that tool's footprint is
detected in the repo, so it never litters your project with rule files for
tools you don't use:
| Tool | File written | Written when |
|---|---|---|
| Cross-tool standard | AGENTS.md |
always |
| Claude Code | CLAUDE.md |
always |
| Cursor | .cursor/rules/threadctx.mdc |
always |
| GitHub Copilot | .github/copilot-instructions.md |
.github/ exists |
| Windsurf | .windsurf/rules/threadctx.md |
.windsurf/ exists |
| Cline | .clinerules/threadctx.md |
.clinerules exists |
| Gemini CLI | GEMINI.md |
.gemini/ exists |
Shared files (AGENTS.md, CLAUDE.md, Copilot, Gemini) get a marker-fenced
block spliced in, preserving your own content around it; dedicated files are
owned in full. This happens automatically the first time the server starts
in a project — you don't need to run init for it. Running init just
triggers it explicitly and prints the result; either way it's idempotent
(safe to re-run, never duplicates). Opt out entirely with
THREADCTX_NO_AUTO_RULES=1, or per-init-call with --no-rules.
The same instruction is also sent as part of the MCP initialize handshake
itself (the protocol's instructions field), so it reaches the model even
before any rules file exists, and for clients that don't read project-rules
files at all. The file-based rules are belt-and-suspenders on top of that,
since not every MCP client is guaranteed to surface instructions
prominently.
Claude Code setup
Add to your Claude Code MCP config (claude mcp add or edit
~/.claude/mcp.json directly):
{
"mcpServers": {
"threadctx": {
"command": "npx",
"args": ["-y", "threadctx-mcp"],
"env": {
"THREADCTX_MODE": "cloud",
"THREADCTX_API_KEY": "tctx_xxx"
}
}
}
}
Cursor setup
Add the same block to .cursor/mcp.json in your project root (or via
Cursor Settings → Tools & MCP):
{
"mcpServers": {
"threadctx": {
"command": "npx",
"args": ["-y", "threadctx-mcp"],
"env": {
"THREADCTX_MODE": "cloud",
"THREADCTX_API_KEY": "tctx_xxx"
}
}
}
}
That's it — the same package and config work in both clients because MCP is a portable, open protocol.
Passive capture — turn git history into memory
Memory shouldn't depend on an agent remembering to call memory_write.
threadctx capture reads the commits landed since its last run, uses your
own LLM provider key to distill the genuinely reusable decisions and
gotchas (skipping trivial commits), dedups them against what's already
stored, and writes the survivors. It's tool-agnostic — it doesn't matter
whether the work happened in Claude Code, Cursor, Copilot, or a plain editor.
# Off by default because it calls an LLM (billed to your provider). Enable it:
export THREADCTX_CAPTURE_ENABLED=1
export ANTHROPIC_API_KEY=sk-... # or OPENAI_API_KEY
npx threadctx-mcp capture --dry-run # preview what it would store
npx threadctx-mcp capture # store them (incremental since last run)
npx threadctx-mcp capture --since=v1.2.0 --diffs # a range, with patches
# Scaffold a GitHub Action that captures every merged PR automatically:
npx threadctx-mcp capture --print-workflow > .github/workflows/threadctx-capture.yml
Capture calls your LLM provider directly — nothing is routed through
threadctx's servers, so local mode keeps its "no network call beyond your own
LLM provider" promise. It is off unless THREADCTX_CAPTURE_ENABLED=1 (or
a one-off --force), so it can never run up token cost as a side effect.
Environment variables
| Variable | Required | Description |
|---|---|---|
THREADCTX_MODE |
no | local (default) or cloud |
THREADCTX_API_KEY |
only in cloud mode | issued via cloud/scripts/create-tenant.ts |
THREADCTX_API_URL |
no | defaults to https://threadctx.dev/api/v1; override for self-hosting |
THREADCTX_REPO |
no | overrides repo auto-detection from git remote |
THREADCTX_DB_PATH |
no | local-mode store path; defaults to ~/.threadctx/local.json |
THREADCTX_NO_AUTO_RULES |
no | set to 1 to disable auto-injecting agent rule files on server start |
THREADCTX_CAPTURE_ENABLED |
for capture |
set to 1 to enable the LLM-backed capture command (off by default) |
THREADCTX_CAPTURE_PROVIDER |
no | force anthropic or openai when both keys are present |
THREADCTX_CAPTURE_MODEL |
no | override the extraction model (defaults: Haiku / gpt-4o-mini) |
ANTHROPIC_API_KEY / OPENAI_API_KEY |
for capture |
your own provider key; capture calls it directly |
Local development
npm install
npm run dev # runs the server via tsx, watches for changes
npm run build # compiles to dist/ for publishing
How the tools work
memory_write(content, tags?)— the agent calls this after resolving a non-obvious bug, making an architectural decision, or learning something worth remembering.memory_query(task_description, max_results?)— the agent calls this before starting risky or repeated work. Results are returned with a consistent attribution footer (· via threadctx — shared team memory (N hits)) so the same string is recognizable whether you're reading Claude Code's terminal output or Cursor's agent panel.
Tool descriptions are written to bias the model toward calling
memory_query proactively, and — as of 0.3.0 — the server reinforces this
two more ways with zero setup required: the MCP initialize response
carries the same instruction to every connecting client, and CLAUDE.md /
.cursor/rules/threadctx.mdc get it auto-injected on first start. MCP tools
are still fundamentally pull-based (no mechanism can force a tool call), but
these three layers together are the strongest guarantee we can build.
CLI subcommands
| Command | What it does |
|---|---|
npx threadctx-mcp |
Runs the MCP server (this is what Claude Code / Cursor launch). Auto-injects project rules on first start in a project. |
npx threadctx-mcp init [--mode=cloud --api-key=…] [--no-rules] |
Sets a repo up for the team: writes .threadctx.json, committable Claude Code/Cursor project MCP configs, and the project-rules files. |
npx threadctx-mcp join |
Joins a repo a teammate already set up: project MCP configs, rules, and per-client instructions. |
npx threadctx-mcp list [--all] [--full] [--json] |
Shows what's stored in the local on-disk memory. |
npx threadctx-mcp capture [--dry-run] [--since=<ref>] [--max=N] [--diffs] [--model=ID] [--print-workflow] |
Distills recent git history into memories via your own LLM key. Off unless THREADCTX_CAPTURE_ENABLED=1 (or --force). |
Browse, search, edit, and prune team (cloud) memory in a human dashboard at threadctx.dev/dashboard — sign in with your team API key.
threadctx MCP questions
How do I add threadctx MCP to Claude Code?
Run claude mcp add --env 'THREADCTX_API_KEY=<YOUR_THREADCTX_API_KEY>' threadctx-mcp -- npx -y threadctx-mcp in your terminal. Add --scope user to make it available in every project.
How do I add threadctx MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does threadctx MCP provide?
It exposes 2 tools, including memory_write, memory_query.
How does the local mode work?
In local mode, memory is stored as a plain JSON file at ~/.threadctx/local.json with zero native dependencies and no network calls except to your LLM provider.
How can I turn git history into memory?
You can use the capture command to distill recent commits into reusable decisions using your own LLM provider key.
Is my API key safe when using cloud mode?
Yes, the API key is read from the THREADCTX_API_KEY environment variable at runtime and is never included in committed files.