# memos-mcp-server

让 AI 助手（Claude Code、Claude Desktop、Cursor、Cherry Studio 等任意 MCP 客户端）通过 **个人访问令牌（PAT）** 读写你的 [Memos](https://github.com/usememos/memos) 笔记。

- **面向任务的工具**：用关键词 / 标签 / 时间范围（"上周"、`7d`、`2026-09`）检索，而不是手写 CEL 表达式；精确编辑（追加、替换片段）不必重写整条 memo；待办清单汇总与勾选；标签批量重命名。
- **本地能力**：上传本地文件或网页 URL 为附件、把附件存到本地、导出为 Markdown（带 YAML front matter，可直接放进 Obsidian）或官方 ZIP 备份。
- **模型能"看"附件**：图片附件以图片内容返回（默认 ≤600px 预览，省 token），文本附件直接返回文本。
- **Prompts 与 Resources**：`daily-review`、`weekly-report`、`tidy-tags` 三个斜杠命令；每条 memo 也是一个可 @ 引用的资源 `memos://memos/<id>`。
- **安全开关**：只读模式、按名禁用工具、限制可访问的本地目录；删除类工具带 `destructiveHint`，客户端会要求确认。
- 支持 **stdio**（本地，默认）和 **Streamable HTTP**（部署在服务器上，每个请求携带自己的 PAT，天然多用户）。

> 基于 Memos **v0.31.0** 的 API 开发，并在 v0.31.0 实例上做了端到端测试。更早的版本（没有 Spaces / Views 的版本）不受支持。

## 快速开始

### 1. 创建访问令牌

Memos → 设置 → **访问令牌** → 创建。令牌只显示一次，形如 `memos_pat_...`。建议为 MCP 单独建一个令牌，便于随时吊销。

### 2. 构建

```bash
git clone https://github.com/bubua12/memos-mcp-server.git
cd memos-mcp-server
npm install
npm run build
```

### 3. 接入客户端

**Claude Code**

```bash
claude mcp add memos --scope user -e MEMOS_URL=https://memos.example.com -e MEMOS_TOKEN=memos_pat_xxx -- node /path/to/memos-mcp-server/dist/index.js
```

**Claude Desktop / Cursor / Cherry Studio 等**（JSON 配置）

```json
{
  "mcpServers": {
    "memos": {
      "command": "node",
      "args": ["/path/to/memos-mcp-server/dist/index.js"],
      "env": {
        "MEMOS_URL": "https://memos.example.com",
        "MEMOS_TOKEN": "memos_pat_xxx",
        "TZ": "Asia/Shanghai"
      }
    }
  }
}
```

调试可以用 MCP Inspector：`MEMOS_URL=... MEMOS_TOKEN=... npm run inspect`。

## 工具

| 工具 | 作用 | 修改 Memos |
| --- | --- | --- |
| `get_overview` | 一次拿到账号、实例版本、统计、写作连续天数、热门标签、Spaces、已保存视图 | |
| `search_memos` | 关键词（支持 `"短语"`）、标签（all/any，父标签匹配子标签）、时间范围、置顶、可见性、属性（有待办 / 链接 / 代码 / 位置）、Space、已保存视图、原始 CEL；分页；可返回全文 | |
| `get_memo` | 单条全文 + 元数据、附件、双向链接、评论 | |
| `list_todos` | 跨 memo 汇总 `- [ ]` 待办，按 memo 分组并编号 | |
| `list_tags` | 标签及数量 | |
| `list_attachments` / `read_attachment` | 列附件；读取附件（图片返回可见图片，文本返回内容） | |
| `download_attachment` | 把附件原文件存到本地（默认不覆盖已有文件，仅 stdio） | |
| `export_memos` | 导出为 Markdown 文件夹（可按条件筛选、下载附件）或官方 ZIP（仅 stdio） | |
| `create_memo` | 新建（可附加标签、置顶、放进 Space、回填创建时间、上传本地文件、关联其它 memo） | ✓ |
| `update_memo` | 改可见性、置顶、归档/恢复、Space、创建时间，或整体替换内容 | ✓ |
| `edit_memo_content` | 追加 / 前插 / 精确替换片段 | ✓ |
| `set_task_status` | 按编号或文字勾选/取消待办 | ✓ |
| `add_comment` | 评论（默认沿用原 memo 的可见性和 Space） | ✓ |
| `link_memos` | 增加 / 移除 / 设置 memo 之间的引用关系 | ✓ |
| `share_memo` | 生成免登录分享链接，可设置过期天数 | ✓ |
| `rename_tag` | 全量重命名标签（含子标签、跳过代码块和 URL、保留"更新时间"），默认只预览 | ✓ |
| `upload_attachment` | 上传本地文件 / URL / 文本为附件，可直接挂到 memo | ✓ |
| `delete_memo` / `delete_attachment` | 永久删除（会提示优先归档） | ✓ |

**Prompts**：`daily-review`（某天回顾）、`weekly-report`（周报）、`tidy-tags`（标签整理方案，确认后调用 `rename_tag`）。
**Resources**：`memos://memos/{id}`，列出最近更新的 50 条。

时间参数支持：`today`、`yesterday`、`this week`、`last week`、`this month`、`last month`、`this year`、`2026`、`2026-09`、`2026-09-28`、`2026-09-28 14:30`、ISO 时间，以及相对量 `30min`、`24h`、`7d`、`2w`、`3mo`、`1y`。日期按进程时区解释，可用 `TZ` 环境变量指定。

## 配置

| 环境变量 | 命令行 | 说明 |
| --- | --- | --- |
| `MEMOS_URL` | `--url` | 实例地址，如 `https://memos.example.com`（结尾的 `/api/v1` 会被忽略） |
| `MEMOS_TOKEN` | `--token` | 个人访问令牌。优先用环境变量，命令行参数会被本机其它进程看到 |
| `MEMOS_TOKEN_FILE` | `--token-file` | 从文件读取令牌（适合 Docker secrets） |
| `MEMOS_READ_ONLY` | `--read-only` | `true` 时只注册不会修改 Memos 的工具 |
| `MEMOS_DISABLED_TOOLS` | `--disable-tools` | 逗号分隔，隐藏指定工具，如 `delete_memo,delete_attachment` |
| `MEMOS_DEFAULT_VISIBILITY` | `--default-visibility` | 新 memo 默认可见性；不设置时沿用你在 Memos 偏好设置里的默认值 |
| `MEMOS_FILE_ROOTS` | `--file-roots` | 逗号分隔的目录白名单，限制上传/下载/导出能访问的本地路径 |
| `MEMOS_TIMEOUT_MS` | `--timeout` | 请求超时，默认 30000 |
| `MEMOS_MCP_TRANSPORT` | `--transport` | `stdio`（默认）或 `http` |
| `MEMOS_MCP_HOST` / `MEMOS_MCP_PORT` | `--host` / `--port` | HTTP 监听地址，默认 `127.0.0.1:8787` |

## HTTP 模式

```bash
node dist/index.js --transport http --port 8787   # MCP 端点：http://127.0.0.1:8787/mcp，健康检查：/healthz
claude mcp add --transport http memos http://127.0.0.1:8787/mcp --header "Authorization: Bearer memos_pat_xxx"
```

- 每个请求用自己的 `Authorization: Bearer <PAT>` 访问 Memos，服务端不需要保存令牌，多人可共用一个部署。
- 只有监听回环地址时，才会在请求未带令牌的情况下退回使用 `MEMOS_TOKEN`；监听 `0.0.0.0` 等地址时，未带令牌的请求一律 401。
- 回环地址上启用 Host/Origin 校验（防 DNS rebinding），其它地址拒绝跨域的浏览器请求。
- 会读写本机文件的能力（`file_path`/`url` 上传、`download_attachment`、`export_memos`）在 HTTP 模式下自动禁用，避免远程调用者读取服务器上的文件。

Docker（镜像默认 HTTP 模式、监听 `0.0.0.0:8787`，因此客户端必须自带令牌）：

```bash
docker build -t memos-mcp-server .
docker run -d -p 127.0.0.1:8787:8787 -e MEMOS_URL=https://memos.example.com memos-mcp-server
```

## 与 Memos 内置 `/mcp` 的区别

Memos v0.31 自带一个 `/mcp` 端点：从 OpenAPI 自动生成的约 36 个工具，1:1 对应 REST 接口，只有 HTTP 传输、只有 tools。它适合"原样调用 API"。本项目则是面向任务的封装：结构化检索参数自动编译成 CEL、紧凑的 Markdown 输出（省上下文）、待办/标签/导出等组合操作、读写本地文件、prompts 与 resources，以及 stdio 支持。两者可以同时使用。

## 安全提示

- 令牌拥有与你账号相同的权限（管理员账号还可以读写其他用户的 memo）。为 MCP 单独创建令牌，最好设置过期时间。
- 上传工具能读取本机文件并存入 Memos。如果会让 AI 处理不可信的内容（网页、邮件等），建议设置 `MEMOS_FILE_ROOTS`，或用 `MEMOS_READ_ONLY` / `MEMOS_DISABLED_TOOLS` 收紧权限。
- `share_memo` 生成的链接任何人都能打开，吊销要到 Memos 网页里操作。

## 开发

```bash
npm run dev          # tsx 直接运行源码
npm test             # 单元测试
npm run typecheck
```

端到端测试需要一个**全新的本地** Memos 实例（初始化脚本只允许 localhost）：

```bash
docker run -d --name memos-e2e -p 127.0.0.1:5231:5230 neosmemo/memos:0.31.0
node scripts/e2e-setup.mjs http://127.0.0.1:5231   # 创建测试管理员和 PAT，写入 .env.e2e
npm run test:e2e                                   # 构建后运行全部工具和 stdio/HTTP 传输测试
```

目录结构：

```
src/
  index.ts          CLI 入口（stdio / http）
  config.ts         参数与环境变量
  context.ts        每个令牌的上下文：API 客户端、当前用户/可见性/Space 缓存、本地路径校验
  server.ts         组装 McpServer（工具、resources、prompts、instructions）
  http.ts           Streamable HTTP 传输
  memos/            REST 客户端、类型、资源名解析、CEL 过滤器构造
  lib/              时间解析、Markdown（待办/标签）、输出格式、MIME
  tools/            各组工具
test/unit, test/e2e
```