threadctx MCPサーバー
✓ 検証済みAIコーディングエージェント向けに、ローカルおよびチーム環境を横断して、設計上の決定事項やプロジェクトのコンテキストを保存・取得するための共有メモリを提供します。
別名 threadctx-dev/threadctx-mcp
- スター
- 1
- ツール
- 2
- ダウンロード数(30日間)
- —
- 最新バージョン
- 0.5.0
- 最終コミット
- 2026年7月29日
- ライセンス
- MIT
threadctx MCPとは
AIコーディングエージェント向けに、ローカルおよびチーム環境を横断して、設計上の決定事項やプロジェクトのコンテキストを保存・取得するための共有メモリを提供します。 2個のツールを提供しており、memory_write, memory_queryなどがあります。
プロジェクトのREADMEから生成された概要
threadctx MCP server について
threadctx-mcpは、AIコーディングエージェントが設計上の決定事項やプロジェクトのコンテキストを保存・取得するための共有メモリレイヤーを提供します。Claude Code、Cursor、Windsurf、GitHub Copilotなどのクライアントを使用する開発者向けに設計されています。このMCP serverは2つのモードで動作します。一つは ~/.threadctx/local.json にデータを保存し、ネットワーク通信を行わないローカルモード、もう一つはチーム全体でのセマンティック検索を可能にするクラウドモード(threadctx.devのAPIキーが必要)です。
ユーザーは init コマンドを使用してチーム用のリポジトリを初期化でき、これにより異なるMCPクライアント用の設定ファイルが作成されます。このサーバーは、モデルが memory_query や memory_write ツールを積極的に使用するように、AGENTS.mdやCLAUDE.mdといったエージェント用ルールファイルを自動的に管理します。コンテキスト収集を自動化したいチーム向けに、capture コマンドを使用することで、開発者自身のLLMプロバイダーのキーを用いてgitの履歴を再利用可能なメモリへと抽出できます。
できること
- 1git履歴からのコンテキスト抽出の自動化LLMプロバイダーを使用する capture コマンドを実行することで、最近のコードコミットを構造化されたメモリに変換できます。
- 2エージェントによるメモリプロトコルの遵守サーバーがルールファイルに指示を自動的に注入するため、エージェントはタスクを開始する前にメモリを照会すべきであることを理解します。
- 3ローカル限定のプロジェクトコンテキストの維持開発者は、外部ネットワークへの依存なしに、プロジェクト固有の知識を自身のマシンに保存できます。
プロジェクトの README から作成されています。すべてのユースケースは、その引用と照らし合わせて確認されています。
threadctx MCPのインストール方法
フォーマット検証日 2026年11月10日Cursor に追加Gooseに追加Claude Codeにthreadctx MCPをインストール
$ claude mcp add --env 'THREADCTX_API_KEY=<YOUR_THREADCTX_API_KEY>' threadctx-mcp -- npx -y threadctx-mcpCursorにthreadctx MCPをインストール
~/.cursor/mcp.json
{
"mcpServers": {
"threadctx-mcp": {
"command": "npx",
"args": [
"-y",
"threadctx-mcp"
],
"env": {
"THREADCTX_API_KEY": "<YOUR_THREADCTX_API_KEY>"
}
}
}
}VS Codeにthreadctx MCPをインストール
.vscode/mcp.json
{
"servers": {
"threadctx-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"threadctx-mcp"
],
"env": {
"THREADCTX_API_KEY": "<YOUR_THREADCTX_API_KEY>"
}
}
}
}VS Code CLIにthreadctx MCPをインストール
$ code --add-mcp '{"name":"threadctx-mcp","type":"stdio","command":"npx","args":["-y","threadctx-mcp"],"env":{"THREADCTX_API_KEY":"<YOUR_THREADCTX_API_KEY>"}}'Claude Desktopにthreadctx MCPをインストール
claude_desktop_config.json
{
"mcpServers": {
"threadctx-mcp": {
"command": "npx",
"args": [
"-y",
"threadctx-mcp"
],
"env": {
"THREADCTX_API_KEY": "<YOUR_THREADCTX_API_KEY>"
}
}
}
}Codexにthreadctx MCPをインストール
$ codex mcp add threadctx-mcp --env 'THREADCTX_API_KEY=<YOUR_THREADCTX_API_KEY>' -- npx -y threadctx-mcpCodex config.tomlにthreadctx MCPをインストール
~/.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>"
Gemini CLIにthreadctx MCPをインストール
$ gemini mcp add -s user -e 'THREADCTX_API_KEY=<YOUR_THREADCTX_API_KEY>' threadctx-mcp npx -- -y threadctx-mcpGemini settings.jsonにthreadctx MCPをインストール
~/.gemini/settings.json
{
"mcpServers": {
"threadctx-mcp": {
"command": "npx",
"args": [
"-y",
"threadctx-mcp"
],
"env": {
"THREADCTX_API_KEY": "<YOUR_THREADCTX_API_KEY>"
}
}
}
}threadctx MCPツール 2
READMEから検出memory_writememory_query
| memory_write | — | |
| memory_query | — |
設定
THREADCTX_API_KEYシークレットAPI 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)
| 名前 | 説明 | 種類 |
|---|---|---|
| THREADCTX_API_KEY | API key for cloud mode, issued at threadctx.dev. Not needed in local mode. | シークレット |
| ANTHROPIC_API_KEY | — | |
| THREADCTX_CAPTURE_ENABLED | — | |
| THREADCTX_MODE | 'local' (default, free, no signup) or 'cloud' (shared team memory) |
自動チェック
実行日 2026年11月14日完全なレポート →自動チェックに合格しました。これはセキュリティ監査ではありません。コードを読み、サーバーに必要最小限のアクセス権を与えてください。 チェックの仕組み
- ソースリポジトリがリンクされており、アクセス可能threadctx-dev/threadctx-mcp is public and reachablegithub.com/threadctx-dev/threadctx-mcp ↗合格
- パッケージがこのリポジトリをソースとして指定threadctx-mcp names threadctx-dev/threadctx-mcp as sourcenpmjs.com/package/threadctx-mcp ↗合格
- ビルドの来歴 (Sigstore 証明)No build attestation published for this release未チェック
- オープンソースライセンス (OSI)MITspdx.org/licenses/MIT.html ↗合格
- 過去1年以内にコミットまたはリリースありLast commit or release 2026-07-29github.com/threadctx-dev/threadctx-mcp ↗合格
- OpenSSF Scorecard未チェック
- パッケージ名が有名なパッケージに酷似していないNo popular package one edit away from threadctx-mcp合格
- パッケージおよびその依存関係に重大な勧告なし99 resolved dependencies checked; no critical advisoryosv.dev ↗合格
- モデルへの隠れた指示がない2 tool descriptions and the README read; no override phrases, credential paths or hidden characters合格
- 破壊的なツールがラベル付けされているNo tool named like delete, drop or exec合格
- リモートエンドポイントが MCP ハンドシェイクに応答未チェック
README
GitHubで見るthreadctx-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のよくある質問
threadctx MCPをClaude Codeに追加するには
ターミナルでclaude mcp add --env 'THREADCTX_API_KEY=<YOUR_THREADCTX_API_KEY>' threadctx-mcp -- npx -y threadctx-mcpを実行します。すべてのプロジェクトで利用するには--scope userを追加します。
threadctx MCPをCursorに追加するには
~/.cursor/mcp.jsonを開き、上記のインストールセクションに示すCursor設定を使ってmcpServersの下にサーバーを追加します。
threadctx MCPが提供するツールは
2個のツールを提供しており、memory_write, memory_queryなどがあります。
ローカルモードはどのように動作しますか?
ローカルモードでは、メモリは ~/.threadctx/local.json にプレーンなJSONファイルとして保存されます。ネイティブな依存関係はなく、LLMプロバイダーへの通信を除いてネットワーク通信は発生しません。
gitの履歴をメモリに変換するにはどうすればよいですか?
captureコマンドを使用することで、自身のLLMプロバイダーのAPIキーを利用して、最近のコミットを再利用可能な決定事項として抽出できます。
クラウドモードを使用する場合、APIキーの安全性は保たれますか?
はい。APIキーは実行時に環境変数 THREADCTX_API_KEY から読み込まれ、コミットされるファイルに含まれることはありません。