# Claude (claude.ai)

将 claude.ai 上的 Claude 作为自定义连接器连接到托管的 Streamable HTTP MCP 端点，使用 OAuth 以及 memory:read 和 memory:write 权限范围。

- Canonical: https://docs.xmemo.dev/zh/docs/mcp/claude
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: de1a3fce819ac5cc3e4ef555fb6ba57c0ae2af9af5e91367ad4efac64a274ea3
- Edition-Digest: 51944398afe396cbe692a3131d3a6dc11e649907419a5b8d7b5f2c56d86890af
- Source-Revision: sha256:ef049dd959bada93a714e560eece53ae72cd3ce2d2ed84bbab43191b9ae93474

## 前置条件

使用支持自定义连接器的 Claude，以及有效的 XMemo 账户。连接信息：

- 界面：网页版 Claude (claude.ai)，通过自定义连接器连接。
- 连接 URL：https://xmemo.dev/mcp。
- 传输方式：Streamable HTTP (streamable-http)。
- 认证模式：使用 PKCE 和动态客户端注册 (Dynamic Client Registration) 的 OAuth 2.0 授权码流程。
- 权限范围：memory:read 和 memory:write。
- 账户：https://xmemo.dev 上的有效 XMemo 账户。

## 将 XMemo 添加为自定义连接器

在 Claude 中添加托管的 MCP 服务器。连接 URL 是唯一的服务器设置：

- 1. 在 Claude 中打开 Customize > Connectors，然后选择 Add custom connector。直达链接：https://claude.ai/customize/connectors?modal=add-custom-connector。
- 2. 名称：XMemo。
- 3. 远程 MCP 服务器 URL：https://xmemo.dev/mcp。
- 4. 添加连接器，然后点击 Connect 开始 OAuth。

## 通过 OAuth 批准访问

Claude 通过动态客户端注册将自身注册为 OAuth 客户端，并在浏览器中打开 XMemo 授权页面。登录后，在同意页面批准 memory:read 和 memory:write。Claude 从此 OAuth 授权中获得凭据。

## 不要添加 bearer token

自定义连接器不需要 API key。不要将 XMemo API key、XMEMO_KEY 或 bearer token 填入连接器；OAuth 授权会提供凭据及其权限范围。

## 在对话中启用 XMemo

返回 Claude，并为当前对话启用 XMemo。之后 Claude 会发现 XMemo 工具及其标题和安全注解。

## 通过真实的 recall 调用进行测试

第一次调用请保持只读。这是一次真实的 recall 调用，而非健康检查占位符，并且不会写入记忆。

```text
recall({ query: "connection check", limit: 1 })
```

## 预期响应（字面形态）

调用成功时会返回下方的公开排序文本形态；其中的引用和内容是已授权记忆空间中的真实值。

```text
### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>
```

## Claude 中可用的工具

在 claude-public 配置文件中，Claude 可以看到 27 个工具。下面按安全注解分组：读取工具从不更改数据，写入工具新增、完成或恢复记录，破坏性工具可能覆盖、更改或删除现有记录。拥有专门参考页面的工具附有链接，其余工具仅在本页说明。

## 读取工具

只读且幂等；这些工具不会更改已存储的数据：

- get_mcp_identity (Check XMemo connection)：返回已认证的连接器身份以及已授予的记忆权限范围。
- [search_memory](/docs/tools/search) (Search XMemo memories)：搜索可见的限定范围记忆或团队记忆记录。
- [recall](/docs/tools/recall) (Recall XMemo memory)：检索最相关的可见记忆。
- [recall_context](/docs/tools/recall-context) (Build XMemo context)：根据可见记忆构建有边界的上下文包。
- memory_overview (Show XMemo memory overview)：汇总可见记忆和近期活动。
- memory_stats (Show XMemo memory statistics)：返回可见记忆的汇总统计。
- memory_activity (Show XMemo memory activity)：显示你自己记忆变更的安全时间线，不暴露原始审计日志。
- analyze_memory_text (Analyze XMemo memory text)：统计某个词或精确短语在可见记忆中出现的次数。
- explain_memory (Explain XMemo memory)：解释某条可见记忆为何存在或为何与查询匹配。
- list_memory_todos (List XMemo memory TODOs)：列出基于记忆的 TODO 和行动项；Claude 通过它读取 TODO。
- list_ledger_transactions (List XMemo Ledger transactions)：列出可见的 Ledger 记录。
- get_monthly_ledger_summary (Summarize XMemo Ledger by month)：按月汇总可见的 Ledger 记录。
- read_memory (Read Memory)：按 recall 或搜索返回的引用，读取一条精确记忆或一个已授权 Document 的有界页面。
- get_project_context (Get project context)：读取你拥有或可访问的某个项目的已授权上下文。

## 写入工具

这些工具新增、完成或恢复记录，未被标记为破坏性：

- add_expense (Record an XMemo Ledger transaction)：创建一条结构化 Ledger 记录。
- complete_memory_todo (Complete XMemo memory TODO)：将一个现有的基于记忆的 TODO 或行动项标记为已完成。
- create_memory_todo (Create XMemo memory TODO)：创建一个基于记忆的 TODO 或行动项。
- [remember](/docs/tools/remember) (Remember in XMemo)：创建一条限定范围的记忆，或对其去重。
- restore_memory (Restore XMemo memory)：恢复被 forget 以默认软删除模式移除的记录。
- record_event (Record a milestone)：追加一条里程碑或交接事件；它从不编辑或删除现有记录。
- create_pending_decision (Save a pending decision)：保存一项未决决策及其上下文和选项，供之后审阅。
- resolve_decision (Resolve a pending decision)：为一项确切的待定决策记录所选结果并将其关闭，同时保留其历史。

## 破坏性工具

这些工具被标记为破坏性，因为它们可能覆盖、更改或删除现有记录：

- [forget](/docs/tools/forget) (Forget XMemo memory, TODO, or Ledger transaction)：删除一条选定的记忆、TODO 或 Ledger 记录；参见下方的“删除与恢复”。
- update_memory (Update XMemo memory)：按精确引用覆盖一条选定记忆的字段。
- update_state (Save working state)：保存或替换一个命名的工作状态检查点，以便之后的对话可以继续。
- [todo](/docs/tools/todos) (Manage XMemo TODOs)：创建、更新或完成你自己的 TODO；参见下方的“Claude 中的 TODO”。
- project (Manage XMemo project)：创建项目，或更改某个已授权项目的记忆、决策、文档和对话链接或设置。

## 删除与恢复

除非你明确要求永久删除，否则通过 forget 进行的删除都可以恢复：

- 默认：forget 执行可恢复的软删除。
- 撤销：restore_memory 恢复被软删除的记录。
- 永久：使用 mode='hard' 的 forget 是永久且不可恢复的。它需要你的明确确认，且被硬删除的记录无法恢复。

## Claude 中的 TODO

在 Claude 中，todo 工具只用于创建、更新或完成 TODO。Claude 使用 list_memory_todos 读取 TODO。todo 参考页面描述了完整的调度器；在 Claude 中，仅将其用于这三种操作。

## Claude Desktop

在 Claude Desktop 中，请从相同的自定义连接器和 OAuth 流程开始。使用 API key 的本地配置仍是备选方案：

- 推荐：将 XMemo 添加为指向 https://xmemo.dev/mcp 的自定义连接器并完成 OAuth。无需 API key。
- 备选：在 claude_desktop_config.json 中配置第一方 xmemo-mcp stdio 代理或 mcp-remote，并使用 XMemo API key。stdio 代理配置请参见 [MCP 概览](/docs/mcp/overview)。

## Claude Code

Claude Code 使用单独的设置。独立 Skill 和直接 MCP 配置请参见 [Claude Code](/docs/mcp/claude-code)。

## 常见错误

OAuth 失败对应真实的令牌端点响应：

- invalid_grant — 授权码无效、已过期或已被使用：在 Claude 中重新连接 XMemo 并再次授权。
- invalid_target — OAuth 资源与此 MCP 服务器不匹配：移除连接器，并使用 https://xmemo.dev/mcp 重新添加。
- 403 insufficient_scope — 授权不包含 memory:read 或 memory:write：批准这两个权限范围后重新连接。

## 更新与移除

Claude 连接器的维护步骤：

- 重新连接：如果 Claude 显示 XMemo 的授权或重新连接提示，请重新连接该连接器并再次完成 OAuth。
- 移除：在 Claude 的连接器设置中移除 XMemo 自定义连接器。