Skip to main content
Glama
memos-mcp-server

memos-mcp-server

by bubua12

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 build

3. 接入客户端

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.js

Claude 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

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 模式

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/e2e

Available Tools

20 tools
add_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 attachmentA
DestructiveIdempotent

Permanently delete an attachment file (it disappears from its memo). Cannot be undone.

Inputs: attachment (required).

delete_memoDelete memoA
DestructiveIdempotent

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 attachmentA
Idempotent

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 contentA
Destructive

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 memoB
Read-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 overviewA
Read-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.

list_attachmentsList attachmentsA
Read-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 tagsA
Read-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-dosA
Read-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 attachmentA
Read-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 tagA
Destructive

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 memosA
Read-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 taskA
Destructive

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.

share_memoCreate share linkA

Create a secret share link that lets anyone with the URL read the memo without signing in. Optionally make it expire. Revoke links in the Memos web UI.

Inputs: memo (required), expires_in_days.

update_memoUpdate memoA
Destructive

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

    A3.9/5.0

    Scored across 20 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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.

      https://mcp.mem.ai/mcp
    • 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

      https://xmemo.dev/mcp
    • Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.

      https://app.contextq.dev/mcp
    • Connect AI to your flomo notes. Search, create, edit notes and manage tags via MCP.

      https://flomoapp.com/mcp

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • F
      license
      A
      quality
      D
      maintenance
      Enables to interact with Memos note-taking service, allowing search, creation, retrieval, and updating of notes through natural language.
      4
      9 npm
      4
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact with Memos instances, supporting multi-instance connections, note management, tags, attachments, and shortcuts.
      16
      19 npm
      2
      MIT