thunked-mcp

Model Context Protocol (MCP) server for Thunked — shared memory for your AI tools. Lets Hermes, Claude Code, Claude Desktop, Cursor, and any MCP-compatible client search, capture, and remember durable project knowledge from your Thunked knowledge base.

For tool-specific setup guides, see docs/integrations/.

For the shortest first-user activation flow, follow the MCP golden path: API key → install thunked-mcp → capture your first memory → recall it from an AI tool.

Quick Start

npx thunked-mcp

The server reads your user-owned API key from the THUNKED_API_KEY environment variable. If you are developing from this repo, it can also fall back to the local source-only CLI config.

Get your API key from the developer settings in the Thunked app. In v1, team destinations are authorized through the key owner's server-side team membership; Thunked does not issue org-scoped keys yet.

First memory smoke test

After connecting the MCP server to Claude Code, Claude Desktop, Cursor, Hermes, or another MCP-compatible client, ask the assistant:

Use thunked_capture to save this first memory:
"Thunked is now connected as shared AI memory for this project. Before important work, search Thunked for prior context. After reusable decisions or bug fixes, save them back to Thunked."

Then start a new chat or clear the assistant's context and ask for an immediate recent-items smoke test:

Use thunked_recent to show the most recent Thunked memories. Confirm that the starter memory appears.

After processing finishes, usually a few seconds later, test search-backed recall:

Use thunked_search to find my Thunked memories about this project. Summarize the top matches and tell me what context should guide the next step.

If the assistant finds the starter memory through recent items and then search, the capture and recall loop is working.

Configuration

Claude Code

Add to your Claude Code MCP config (.claude/settings.json or project settings):

{
  "mcpServers": {
    "thunked": {
      "command": "npx",
      "args": ["thunked-mcp"],
      "env": {
        "THUNKED_API_KEY": "thunked_xxx"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "thunked": {
      "command": "npx",
      "args": ["thunked-mcp"],
      "env": {
        "THUNKED_API_KEY": "thunked_xxx"
      }
    }
  }
}

Environment Variables

| Variable | Description | Default | | ------------------ | -------------------- | ------------------------ | | THUNKED_API_KEY | Your Thunked API key | Required for npm/npx use | | THUNKED_BASE_URL | API base URL | https://app.thunked.ai |

Tools

thunked_search

Search your Thunked memory for saved knowledge.

Input:

• query (string, required) — keywords, topics, questions, or natural language
• limit (number, optional) — max results to return (default: 10)

Example usage: "Search my Thunked for notes about React Server Components"

thunked_capture

Save something to your Thunked memory.

Input:

• content (string, required) — the URL or text to capture
• type ("text" | "link", optional) — auto-detected if omitted
• tags (string[], optional) — tags to organize the item
• target_team / target_collection_id (optional) — capture into a team Inbox or shared collection you can write to using your user-owned API key

Example usage: "Save this article about database indexing to my Thunked"

thunked_recent

Get your most recently captured items.

Input:

• limit (number, optional) — number of items (default: 10, max: 50)

Example usage: "What have I saved to Thunked recently?"

thunked_learnings

Get your latest Weekly Learnings digest — an AI-generated summary of themes, insights, and connections from your recent captures.

Input:

• current (boolean, optional) — if true, get the in-progress week instead of the latest completed digest

Example usage: "What did I learn this week according to Thunked?"

thunked_related

Find items related to a topic, filename, code snippet, or concept.

Input:

• context (string, required) — the topic, filename, error message, or concept

Example usage: "Find anything in my Thunked related to this error message"

thunked_project_context

Retrieve a compact, search-backed context packet for a project or repository before an agent starts coding, planning, or debugging.

Input:

• project (string, required) — project, product, or workspace name
• repo (string, optional) — repository name or owner/repo slug
• query (string, optional) — extra terms such as auth, billing, MCP, bugfix, or decision
• limit (number, optional) — max items to include (default: 10, max: 25)
• scope (personal | team | all, optional) — API read scope, defaulting to personal

Important limitation: this combines typed structured-memory metadata filters (memory_kind, memory_project, memory_repo) with the existing /api/v1/items?q=... search path, then merges and dedupes results. It returns item summaries; full item bodies are not included yet.

Example usage: "Before changing auth, get Thunked project context for Thunked / shugart/jons-brain about auth decisions."

thunked_list_structured_memory

List structured memories saved by Thunked MCP, grouped by kind.

Input:

• kind (decision | bugfix | note, optional) — omit to search all supported kinds
• project (string, optional) — project/product/repo term to narrow results
• query (string, optional) — extra search terms
• limit (number, optional) — max items per kind (default: 5, max: 20)
• scope (personal | team | all, optional) — API read scope, defaulting to personal

Behavior: queries typed structured-memory metadata filters first (based on the persisted memory envelope). When the API does not support the filters or typed filtering returns no matches, it falls back to a legacy marker search over markdown text items such as Agent Memory Decision. Marker-only memories from older package versions stay reachable through that fallback, but are omitted once typed matches exist for the same filter set.

Example usage: "List my Thunked decision memories for the billing project."

Deferred retrieval: thunked_get_item

Single-item retrieval by id is intentionally not exposed in this package version because the public API does not currently provide a body-returning GET /api/v1/items/{id} endpoint for API keys. That endpoint should land in a separate API-gated PR with user/team access tests before MCP adds the tool.

Structured agent-memory tools

These tools save durable agent memories via the existing /api/v1/items endpoint. Each save persists a typed memory envelope (metadata.memory, schema version 1) alongside a readable markdown body, so memories stay human-readable and — on API deployments that support typed item filters — deterministically retrievable. The envelope always carries kind, title, and summary; project, repo, labels, source, and kind-specific fields are included only when the tool accepts them and they are provided (thunked_remember_note takes no project/repo; thunked_remember_bugfix takes repo but no project).

Important notes for this milestone:

• These saves consume the same item quota/rate limits as any other capture.
• Typed retrieval is available: thunked_list_structured_memory and thunked_project_context filter on the persisted envelope (memory_kind, memory_project, memory_repo). A legacy marker search runs only when typed filtering is unsupported by the API or returns no matches, so memories saved before envelope persistence shipped remain reachable until typed matches exist for the same filters.
• labels, when provided, are stored in the memory envelope and folded into the markdown body. They are not API tags.
• thunked_remember_note is separate from thunked_learnings; it does not create or modify Weekly Learnings digests.

thunked_remember_note

Save a structured note, learning, workflow, prompt, or research finding (typed envelope + markdown).

Input:

• title (string, required) — short human-readable title
• summary (string, required) — durable note/learning to remember
• context (string, optional) — why this matters or where it came from
• source (string, optional) — URL, file path, issue, PR, or conversation reference
• labels (string[], optional) — labels written into the markdown body
• target_team / target_collection_id (optional) — same targeting behavior as thunked_capture

thunked_remember_decision

Save a structured decision record (typed envelope + markdown).

Input:

• title (string, required) — short decision title
• decision (string, required) — decision that was made
• rationale (string, optional) — why this choice won
• alternatives (string[], optional) — rejected alternatives/tradeoffs
• project, repo, context, labels, target_team, target_collection_id (optional)

thunked_remember_bugfix

Save a structured bugfix record (typed envelope + markdown).

Input:

• title (string, required) — short bugfix title
• problem (string, required) — symptom or failing behavior
• fix (string, required) — what fixed it
• root_cause, files, commands, verification, context, repo, labels, target_team, target_collection_id (optional)

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

License

MIT