如何让 Cursor、Claude Code 等 MCP 客户端连接 Mem0 托管 MCP 服务器
如何让 Cursor、Claude Code 等 MCP 客户端连接 Mem0 托管 MCP 服务器
AI 编码客户端(Cursor、Claude Code 等)在会话之间不会保留任何上下文。Mem0 提供了一个由官方托管的 MCP 服务器,让支持 MCP(Model Context Protocol)的客户端通过 HTTPS 直接连接 https://mcp.mem0.ai/mcp,调用一套记忆工具(保存、检索、更新、删除记忆)。服务器由 Mem0 托管,你本机不运行任何服务,记忆存放在你的 Mem0 账户中而不是本地磁盘。本文的目标是:把客户端指向该托管服务器、完成鉴权,并用一次"存一次、读回一次"的往返测试确认连接真正可用。
前提条件
按 Mem0 MCP 文档 的要求,开始前需要准备:
- 一个 Mem0 Platform 账户,并从 dashboard 获取 API key(key 以
m0-开头)。 - Node.js 18+(
npx命令依赖它)。 - 一个支持 MCP 的客户端,文档列出的范围为:Claude、Claude Code、Codex、Cursor、Windsurf、VS Code、OpenCode。
注意:服务器是带鉴权的,"连上"不等于"能用"。完成连接配置后还要完成下面两种登录方式之一,否则服务器会返回 401 Authentication required,客户端会把连接报告为失败。
用 npx mcp-add 一条命令接入
mcp-add 是一个辅助工具,它会把 Mem0 服务器写进每个客户端自己的 MCP 配置文件,不需要手动编辑。在终端执行:
npx mcp-add \
--name mem0-mcp \
--type http \
--url "https://mcp.mem0.ai/mcp" \
--clients "claude code,cursor,windsurf,vscode,opencode"
--clients 里只保留你实际使用的客户端。执行完成后重启每个客户端,让它加载新写入的服务器配置。
如果提示 npx: command not found,说明 Node.js 未安装,先安装 Node.js 再重试。
两个例外:
- Claude Desktop 不支持
mcp-add,它会拒绝该服务器(报 "not a valid MCP server"),需要通过 Settings UI 手动添加,见下文。 - 如果不想依赖辅助工具,各客户端的手动配置见"手动配置单个客户端"一节。
选择鉴权方式
连接成功后,服务器还需要确认你是谁。文档给出两种方式:
方式一:通过客户端浏览器登录(默认,推荐)
大多数客户端会自动处理。第一次让 agent 使用 Mem0 工具时,客户端会打开一个浏览器窗口,请求你授权访问 Mem0 账户。批准一次后,客户端保存 token 并在需要时自动刷新。如果你按上面的 quick setup 操作,默认走的就是这条路径。
方式二:使用 API key(bearer token)
适用于没有浏览器登录流程的客户端,或 CI 这类 headless 环境。把 API key 作为 bearer token 发送,具体放在哪里取决于客户端,语法见下面各客户端的手动配置。文档同时提醒:key 从 Mem0 dashboard 获取,不要把它放进任何会提交到版本库的文件。
手动配置单个客户端
mcp-add 不可用、或你想自己确认写入内容时,按客户端修改对应配置文件。
Claude Code(MCP only)
把以下内容加入 Claude Code 的 MCP 配置文件 .mcp.json:
{
"mcpServers": {
"mem0": {
"type": "http",
"url": "https://mcp.mem0.ai/mcp/",
"headers": {
"Authorization": "Token ${MEM0_API_KEY}"
}
}
}
}
${MEM0_API_KEY} 是对 shell 环境变量的引用,客户端在发起请求时解析它,因此需要先让 shell 持有这个变量。下面的命令会把一行 export 追加到你的 shell profile(会修改 ~/.zshrc 或 ~/.bashrc),并把 m0-your-api-key 替换成 dashboard 里你的真实 key:
echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.zshrc
source ~/.zshrc
用 echo $MEM0_API_KEY 确认,应打印出你的 key。
Claude Code 集成文档 还提供一条可选的完整插件路径:claude plugin marketplace add mem0ai/mem0 然后 claude plugin install mem0@mem0-plugins。插件在 MCP 服务器之外还附带 lifecycle hooks 和 Mem0 SDK skill(MCP-only 安装没有这两项);安装插件后开新会话运行 /mem0:onboard 可以校验 API key 与 MCP 连接。如果你只需要 MCP 工具,用上面的配置即可。
Cursor
把以下内容加入 .cursor/mcp.json(Authorization 头里的 ${env:MEM0_API_KEY} 是 Cursor 的环境变量引用语法,同样要求 shell 已导出 MEM0_API_KEY):
{
"mcpServers": {
"mem0": {
"url": "https://mcp.mem0.ai/mcp/",
"headers": {
"Authorization": "Token ${env:MEM0_API_KEY}"
}
}
}
}
Cursor 集成文档 有一个明确警告:如果 Cursor 里已经配置过一个名为 mem0 的 MCP server,先删掉旧条目再添加,否则会出现重复工具。
另外,如果不走 API key 而用浏览器登录,Mem0 MCP 文档 给出的 Cursor 手工配置是不带 headers 的:
{
"mcpServers": {
"mem0-mcp": {
"type": "http",
"url": "https://mcp.mem0.ai/mcp"
}
}
}
两种写法对应上面两种鉴权方式,按你选择的方式二选一,不要同时保留两份服务器条目。
Claude Desktop
Claude Desktop 走 UI 配置,不经过配置文件:
- 打开 Claude Desktop,进入 Settings > Connectors。
- 点击 Add custom connector。
- 输入名称(例如
mem0-mcp)和 URLhttps://mcp.mem0.ai/mcp。 - 保存,然后重启 Claude Desktop。
首次使用 Mem0 工具时它会打开浏览器完成登录,流程同"通过客户端浏览器登录"。
Codex
Codex 从 ~/.codex/config.toml(TOML 格式,不是 JSON)读取 MCP 服务器,在文件中加入:
[mcp_servers.mem0]
url = "https://mcp.mem0.ai/mcp"
bearer_token_env_var = "MEM0_API_KEY"
然后在启动 Codex 的 shell 中导出 MEM0_API_KEY,重启 Codex。两点注意:
codex mcp add只支持 stdio 服务器,HTTP 服务器必须直接写config.toml,或者在 Codex 应用里走 Plugins → Connect to a custom MCP → Streamable HTTP 界面添加。- Codex 使用的服务器名是
mem0(其他客户端是mem0-mcp),这是为了让它与文档提到的 Codex 侧 bundled plugin 注册的名称一致。
验证连接是否成功
重启客户端后,按 Mem0 MCP 文档 的做法做一次往返测试:让 agent 存一条记忆,然后在之后的消息里读回来:
You: Remember that I prefer TypeScript over JavaScript for new projects.
Agent: Saved.
You: What language do I prefer for new projects?
Agent: You prefer TypeScript over JavaScript.
第二次回答只有记忆真正存入服务器才成立,所以这是一个真实的往返测试,而不是模型复述上下文。过程中观察两点:
- 客户端的工具列表(多数客户端有 tools 或 MCP 面板)里应出现 Mem0 的工具,如
add_memory、search_memories、get_memories等; - 如果你没有配置 API key,第一次工具调用应触发上面的浏览器登录。
集成文档给出的等价验证方式是:开一个新会话,直接问 "List my mem0 entities" 或 "Search my memories for hello",mem0 工具出现并有响应即配置成功。
也可以在客户端之外确认:打开 Mem0 dashboard,agent 保存的记忆会出现在那里。
遇到问题时按现象排查
| 现象 | 含义 | 处理 |
|---|---|---|
401 或 "Authentication required" |
客户端连上了但未登录 | 完成浏览器登录,或把 API key 配置为 bearer token |
| "Connection refused" / "failed to connect" | 客户端连不到服务器 | 检查网络,再确认 URL 恰好是 https://mcp.mem0.ai/mcp |
| agent 看不到 Mem0 工具 | 配置已写入但客户端未重载 | 重启客户端;工具仍缺失时,确认 mcp-add 写入的是该客户端真正读取的配置文件 |
npx: command not found |
Node.js 未安装 | 安装 Node.js 18+ |
| "Invalid API key" | key 错误、已被吊销或属于其他账户 | 到 Mem0 dashboard 重新获取一个 key |
补充几条各客户端文档中的具体检查:
- "Connection failed"(Cursor / Claude Code):在 shell 里执行
echo $MEM0_API_KEY,若为空,说明 key 没有持久化,按"手动配置"一节把它加进 shell profile 并source。 - Cursor 工具不出现:到 Cursor Settings > MCP 确认
mem0服务器显示为 connected。 - Claude Code 每次会话显示 "Mem0 Inactive":API key 没有持久化,按上一条处理。
边界与说明
- 记忆存放在你的 Mem0 账户中,本机不运行服务器,也没有本地存储副本。
- 文档中
mcp-add命令使用的 URL 不带尾部斜杠(https://mcp.mem0.ai/mcp),而 Cursor / Claude Code 集成文档的手动配置示例使用带斜杠的https://mcp.mem0.ai/mcp/,两处均按原文保留,对应各自来源文档的配置写法。 - 完整工具列表(含
list_entities、update_memory等)及更多客户端细节,可继续查阅仓库中的 docs/platform/mem0-mcp.mdx、docs/integrations/cursor.mdx、docs/integrations/claude-code.mdx 和 docs/integrations/codex.mdx。