文档

Memo MCP 接入指南

在线阅读：/doc（与本文同步，直达锚点：/doc#memo-mcp）。自建部署与排障见 docs/MCP/ops-external-mcp.md（运维向，不随站内页发布）。

---

一、快速开始

1. 打开 设置 → 访问凭证，创建密钥并立即复制保存（关闭后无法再看）。
2. 创建时勾选权限：

- 只让 AI 查看便签 → 勾选 Memo · 读取

- 还要 新建/修改/删除 → 再加 Memo · 写入

1. 在 Cursor / Claude / LobeChat 中粘贴配置，把占位符 <你的凭证> 换成刚保存的那串密钥。
2. 按权限选连接地址（见下一节），保存后由客户端自动完成 initialize 与会话；无需手写 HTTP。

默认 90 天过期（也可选 30 天或永不过期）；若怀疑泄露，请在设置里立即撤销。

---

二、权限与连接地址（请先分清）

补充：

• 也可用请求头 X-MCP-Readonly: true 代替只读地址。
• 密钥只有「Memo · 读取」时，即使连 /mcp，服务端也会按只读处理。

---

三、客户端配置示例

Cursor — 仅查看便签

{
  "mcpServers": {
    "mesq-memo-readonly": {
      "url": "https://<your-host>/mcp/readonly",
      "headers": { "Authorization": "Bearer <你的凭证>" }
    }
  }
}

Cursor — 可修改便签

{
  "mcpServers": {
    "mesq-memo": {
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer <你的凭证>" }
    }
  }
}

Claude Desktop（仅查看）

claude mcp add --transport http mesq-memo-readonly https://<your-host>/mcp/readonly \
  --header "Authorization: Bearer <你的凭证>"

LobeChat

路径：设置 → 技能 → 自定义 → Streamable HTTP。下方为可写示例；若密钥只有「Memo · 读取」，请把 url 中的 /mcp 改为 /mcp/readonly。

{
  "mcpServers": {
    "mesq-memo": {
      "url": "https://<your-host>/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer <你的凭证>" }
    }
  }
}

兼容情况

会话由响应头 Mcp-Session-Id 维护；约 30 分钟无活动会失效（后台每 5 分钟扫描清理），需重新连接。多机部署须按该 ID 做负载均衡 sticky（详见运维手册）。

---

四、工具一览（15 个）

list_memos 常用参数

search_memos 常用参数

带附件新建便签

1. upload_memo_resource → 得到 path
2. create_memo → resources: [{ path, displayName, fileSize, mimeType, type }]

附件怎么读

MCP 资源 URI 形如 memo://resource/{encodedPath}，与 mcp_uri 对应。

---

五、内容与配额限制

---

六、常见问题

调用过于频繁时会限速；具体阈值见下文「开发者参考」。

---

七、暂不支持

• OAuth 一键登录（当前仅访问密钥）
• resources/subscribe、MCP Prompts
• structuredContent / outputSchema

---

开发者参考

协议要点

• 传输：Streamable HTTP；服务名 mesq-memo，版本 1.2.0。
• 鉴权：Authorization: Bearer <token>；读操作至少需 scope memo:read，写操作需 memo:write。
• 手动调试时：POST /mcp 或 /mcp/readonly 发 initialize，后续请求（含 GET / DELETE）都要带 Mcp-Session-Id。

限流（可按 PAT / IP）

环境变量：MCP_RATE_LIMIT_ENABLED、MCP_RATE_LIMIT_PROFILE=normal|relaxed|off。

429 响应：Retry-After（秒）；body 含 error.code=RATE_LIMITED、error.retryAfterSeconds。客户端优先读 header。

连接层限流仅作用于 initialize 与 tools/list；read_memo_resource 单独计入附件读桶。

工具子集过滤（请求头）

• X-MCP-Tools：白名单（逗号分隔）
• X-MCP-Exclude-Tools：黑名单
• X-MCP-Toolsets：memos / tags / resources
• 以上过滤在 initialize 建立会话与工具注册时生效；后续调用沿用该会话内的工具子集。

版本说明

当前为上线观察档（500/150/100/50），首月复盘后可调整阈值。