memos-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@memos-mcp-server show my todos from last week and check off the finished ones"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
memos-mcp-server
让 AI 助手(Claude Code、Claude Desktop、Cursor、Cherry Studio 等任意 MCP 客户端)通过 个人访问令牌(PAT) 读写你的 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. 构建
git clone https://github.com/bubua12/memos-mcp-server.git
cd memos-mcp-server
npm install
npm run build3. 接入客户端
Claude Code
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.jsClaude Desktop / Cursor / Cherry Studio 等(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。
Related MCP server: Memos MCP Server
工具
工具 | 作用 | 修改 Memos |
| 一次拿到账号、实例版本、统计、写作连续天数、热门标签、Spaces、已保存视图 | |
| 关键词(支持 | |
| 单条全文 + 元数据、附件、双向链接、评论 | |
| 跨 memo 汇总 | |
| 标签及数量 | |
| 列附件;读取附件(图片返回可见图片,文本返回内容) | |
| 把附件原文件存到本地(默认不覆盖已有文件,仅 stdio) | |
| 导出为 Markdown 文件夹(可按条件筛选、下载附件)或官方 ZIP(仅 stdio) | |
| 新建(可附加标签、置顶、放进 Space、回填创建时间、上传本地文件、关联其它 memo) | ✓ |
| 改可见性、置顶、归档/恢复、Space、创建时间,或整体替换内容 | ✓ |
| 追加 / 前插 / 精确替换片段 | ✓ |
| 按编号或文字勾选/取消待办 | ✓ |
| 评论(默认沿用原 memo 的可见性和 Space) | ✓ |
| 增加 / 移除 / 设置 memo 之间的引用关系 | ✓ |
| 生成免登录分享链接,可设置过期天数 | ✓ |
| 全量重命名标签(含子标签、跳过代码块和 URL、保留"更新时间"),默认只预览 | ✓ |
| 上传本地文件 / URL / 文本为附件,可直接挂到 memo | ✓ |
| 永久删除(会提示优先归档) | ✓ |
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 环境变量指定。
配置
环境变量 | 命令行 | 说明 |
|
| 实例地址,如 |
|
| 个人访问令牌。优先用环境变量,命令行参数会被本机其它进程看到 |
|
| 从文件读取令牌(适合 Docker secrets) |
|
|
|
|
| 逗号分隔,隐藏指定工具,如 |
|
| 新 memo 默认可见性;不设置时沿用你在 Memos 偏好设置里的默认值 |
|
| 逗号分隔的目录白名单,限制上传/下载/导出能访问的本地路径 |
|
| 请求超时,默认 30000 |
|
|
|
|
| HTTP 监听地址,默认 |
HTTP 模式
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,因此客户端必须自带令牌):
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 网页里操作。
开发
npm run dev # tsx 直接运行源码
npm test # 单元测试
npm run typecheck端到端测试需要一个全新的本地 Memos 实例(初始化脚本只允许 localhost):
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/e2eAvailable Tools
20 toolsadd_commentComment on memoA
Add a comment to a memo. The comment gets the same visibility (and space) as the memo unless you set one.
Inputs: memo (required), content (required), visibility.
create_memoCreate memoA
Create a new memo from Markdown. Tags are written inline as #tag (or pass tags to append them). Task lists use "- [ ] item". Visibility defaults to your Memos preference (usually PRIVATE); memos placed in a space default to SPACE visibility. Local files in attachments are uploaded and attached.
Inputs: content (required), tags, space, pinned, +4 more.
delete_attachmentDelete attachmentADestructiveIdempotent
Permanently delete an attachment file (it disappears from its memo). Cannot be undone.
Inputs: attachment (required).
delete_memoDelete memoADestructiveIdempotent
Permanently delete a memo. This cannot be undone. Prefer update_memo with archived=true unless the user explicitly asked to delete.
Inputs: memo (required).
download_attachmentDownload attachmentAIdempotent
Save the original file of an attachment to a local path. Existing files are not overwritten unless overwrite=true.
Inputs: save_to (required), attachment (required), overwrite.
edit_memo_contentEdit memo contentADestructive
Make a targeted edit without resending the whole memo: append text at the end, prepend it at the start, or replace an exact snippet. append/prepend join with a single newline (start text with "\n" for a blank line). For replace, old_text must match exactly once unless replace_all=true.
Inputs: memo (required), text (required), operation (required), old_text, +1 more.
export_memosExport memosA
Back up memos to a local folder. format=markdown writes one .md file per memo (YAML front matter with id, times, tags, visibility; attachments downloaded next to it) and accepts the same filters as search_memos — handy for Obsidian or offline analysis. format=zip saves the official Memos export archive of ALL your memos (filters ignored), which Memos can import again.
Inputs: output_dir (required), to, has, from, +12 more.
get_memoGet memoBRead-onlyIdempotent
Read one memo in full: Markdown content, metadata (times, visibility, pinned, space, tags, open tasks), attachments, linked memos and comments.
Inputs: memo (required), include_comments.
get_overviewMemos overviewARead-onlyIdempotent
Orientation in one call: who you are signed in as, the Memos instance and version, memo/task/tag statistics, recent activity, spaces you belong to, and saved views (with their filters). Call this first when you need context.
Inputs: no named parameters.
link_memosLink memosADestructive
Manage a memo's references to other memos (shown as linked memos in Memos). action=add keeps existing links, remove deletes the given ones, set replaces the whole list.
Inputs: memo (required), targets (required), action.
list_attachmentsList attachmentsARead-onlyIdempotent
List attachments of one memo, or search all your attachments by file name, MIME type or unlinked status, newest first.
Inputs: memo, type, limit, creator, +3 more.
list_tagsList tagsARead-onlyIdempotent
List the tags used in your active memos with how many memos carry each. Parent tags count their children (#work includes #work/project).
Inputs: sort, prefix.
list_todosList to-dosARead-onlyIdempotent
Collect task-list items ("- [ ] …") across your memos, grouped by memo, with each task's number for set_task_status. By default shows only open tasks from active memos; narrow with keywords, tags, time range or space.
Inputs: to, from, tags, view, +7 more.
read_attachmentRead attachmentARead-onlyIdempotent
Open an attachment: images come back as viewable pictures (a ≤600px preview unless full_size=true), text files as text. To store the original file locally use download_attachment.
Inputs: attachment (required), full_size.
rename_tagRename tagADestructive
Rename a tag across all of your memos (active and archived) by rewriting "#old" to "#new" in their content; child tags follow (#old/x → #new/x). Code blocks and URLs are left alone, and each memo keeps its "updated" time. Runs as a preview unless dry_run=false — show the preview to the user first.
Inputs: to (required), from (required), dry_run.
search_memosSearch memosARead-onlyIdempotent
Find memos by keywords, tags, time range, pinned state, visibility, content properties, space or saved view, newest first. By default searches only your own active (non-archived) memos. Each result shows the memo id, time, visibility, tags and a one-line snippet; set full_content=true to get complete Markdown (useful for summarizing). Use next_page_token to page.
Inputs: to, has, from, sort, +14 more.
set_task_statusCheck / uncheck taskADestructive
Mark one task-list item in a memo as done or not done. Identify it by its number from list_todos/get_memo order (task_index) or by a unique piece of its text (task_text).
Inputs: memo (required), done, task_text, task_index.
update_memoUpdate memoADestructive
Change memo properties — visibility, pinned, archived, space, creation time — and/or replace the ENTIRE content. For small text changes prefer edit_memo_content so the rest of the memo is not rewritten. Only the fields you pass are changed.
Inputs: memo (required), space, pinned, content, +3 more.
upload_attachmentUpload attachmentA
Upload a local file (file_path), a web URL (url), or inline text as a Memos attachment, optionally attaching it to a memo. Returns the attachment name for use with create_memo.
Inputs: url, memo, text, filename, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools target distinct resources and actions, and descriptions clarify boundaries (e.g., read_attachment vs download_attachment). The only real overlap is update_memo vs edit_memo_content, which both modify memo content, though the descriptions differentiate their intended use cases.
All tool names use consistent snake_case and follow a verb_noun pattern (e.g., create_memo, list_tags, set_task_status). The pattern extends even to multi-word nouns like edit_memo_content and upload_attachment.
20 tools is on the heavy side but each covers a distinct operation across memos, attachments, tags, tasks, comments, links, and sharing. The set feels comprehensive rather than redundant, though slightly over the ideal 3-15 range.
Core memo lifecycle (create, read, update, delete, search, edit, share, export) is well covered, along with attachments, tags, and tasks. Minor gaps exist—no tools for deleting or editing comments, revoking share links, or managing spaces/saved views—but these are either delegated to the web UI or less critical for agent workflows.
Related MCP Connectors
Securely search, create, and organize your Mem notes and collections from AI assistants.
XMemo is a user-owned Memory OS for AI agents, providing a shared, persistent memory layer across AI assistants, IDEs, CLIs, tools, projects, and sessions. It enables ChatGPT, Claude, Codex, Cursor, Gemini, and other supported AI clients to access authorized long-term context without requiring users to repeatedly explain their preferences, project decisions, or previous work. Beyond basic memory storage and retrieval, XMemo supports semantic search, contextual recall, memory updates and corrections, source attribution, version history, project-scoped context, task tracking, and governed memory lifecycle management. Identity-aware access controls, scoped authorization, and memory isolation help users manage which agents and workflows can access their information. XMemo also provides advanced capabilities for structured knowledge, reusable procedures, and memory consolidation through its broader Memory OS platform. Connect through hosted MCP with OAuth or bearer-token authentication, or integrate directly through REST APIs and supported client tools. Memory remains available across authorized clients and sessions, with user-controlled access, export, and deletion. Website: https://xmemo.dev Documentation: https://xmemo.dev/docs
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Connect AI to your flomo notes. Search, create, edit notes and manage tags via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with Memos instances for personal note-taking and knowledge management. Supports creating, searching, updating, and organizing memos with tags, dates, and visibility settings through natural language.MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with Memos instances for knowledge management. Supports searching, creating, updating, and retrieving memos with markdown content, tags, and visibility controls.45MIT
- FlicenseAqualityDmaintenanceEnables to interact with Memos note-taking service, allowing search, creation, retrieval, and updating of notes through natural language.49 npm4-
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with Memos instances, supporting multi-instance connections, note management, tags, attachments, and shortcuts.1619 npm2MIT