threadctx MCP server
✓ 인증됨AI 코딩 에이전트가 로컬 및 팀 환경 전반에서 아키텍처 결정 사항과 프로젝트 컨텍스트를 저장하고 검색할 수 있는 공유 메모리를 제공합니다.
다른 이름 threadctx-dev/threadctx-mcp
- 스타
- 1
- Tools
- 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과 같은 클라이언트를 사용하는 개발자를 위해 설계되었습니다. 이 서버는 두 가지 모드로 작동합니다. 데이터 네트워크 호출 없이 ~/.threadctx/local.json의 일반 JSON 파일에 저장하는 로컬 모드와, threadctx.dev의 API 키가 필요한 팀 단위의 시맨틱 검색용 클라우드 모드가 있습니다.
사용자는 init 명령어를 사용하여 팀을 위한 저장소를 초기화할 수 있으며, 이 과정에서 다양한 MCP 클라이언트를 위한 설정 파일이 생성됩니다. 서버는 AGENTS.md 및 CLAUDE.md와 같은 에이전트 규칙 파일을 자동으로 관리하여 모델이 memory_query 및 memory_write 도구를 선제적으로 사용하도록 보장합니다. 컨텍스트 수집을 자동화하려는 팀의 경우, capture 명령어를 통해 개발자의 LLM 제공업체 키를 사용하여 git history를 재사용 가능한 메모리로 추출할 수 있습니다.
활용 사례
- 1git history로부터 컨텍스트 추출 자동화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를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
threadctx MCP는 어떤 도구를 제공하나요?
2개 도구를 제공합니다. 예: memory_write, memory_query.
로컬 모드는 어떻게 작동하나요?
로컬 모드에서는 별도의 네이티브 의존성 없이, LLM 제공업체로의 호출을 제외한 네트워크 통신 없이 ~/.threadctx/local.json 경로의 일반 JSON 파일에 메모리가 저장됩니다.
git history를 메모리로 변환하려면 어떻게 하나요?
사용 중인 LLM 제공업체의 API 키를 사용하여 capture 명령어를 실행하면 최근 커밋 내용을 재사용 가능한 결정 사항으로 추출할 수 있습니다.
클라우드 모드 사용 시 API 키가 안전한가요?
네, API 키는 런타임 시 THREADCTX_API_KEY 환경 변수에서 읽어오며, 커밋되는 파일에는 절대 포함되지 않습니다.