keep-mcp

keep-mcp

Google Keep 的 MCP 服务

贡献指南和所需的视觉证据请参见 CONTRIBUTING.md。

使用方法

1. 将 MCP 服务添加到你的 MCP 服务列表中：

  "mcpServers": {
    "keep-mcp-pipx": {
      "command": "pipx",
      "args": [
        "run",
        "keep-mcp"
      ],
      "env": {
        "GOOGLE_EMAIL": "Your Google Email",
        "GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
      }
    }
  }

或者使用 uvx：

  "mcpServers": {
    "keep-mcp": {
      "command": "uvx",
      "args": [
        "keep-mcp"
      ],
      "env": {
        "GOOGLE_EMAIL": "Your Google Email",
        "GOOGLE_MASTER_TOKEN": "Your Google Master Token - see README.md"
      }
    }
  }

2. 添加你的凭据：

• GOOGLE_EMAIL：你的 Google 账号邮箱地址
• GOOGLE_MASTER_TOKEN：你的 Google 账号主令牌

获取 Google 主令牌

keep-mcp 使用 gkeepapi，通过非官方私有 API 连接到 Google Keep。Google 主令牌拥有对你账号的完整访问权限。请像对待密码一样妥善保管，切勿提交或分享。

请使用 gpsoauth 文档中介绍的浏览器辅助令牌交换方式。选择你想要运行该交换的方式：

• 本地 Python： 按照 gpsoauth 的替代流程操作。
• Docker： 按照 gkeepapi 的“获取主令牌”说明操作。此方式无需在本地安装 Python，即可运行相同的交换流程。

两种方式都需要 gpsoauth 文档中介绍的浏览器 oauth_token。

旧版说明可能会要求你提供 Google 密码或应用专用密码，并调用 perform_master_login()。该流程不可靠，可能返回 BadAuthentication。请改用上述浏览器辅助流程。

功能

查询和读取工具

• find：搜索笔记（默认不区分大小写），并可选按标签、颜色、置顶、归档、已移至回收站、创建／更新时间范围（ISO 8601，UTC）和结果数量上限进行筛选
• get_note：通过 ID 获取单条笔记

创建和更新工具

• create_note：使用标题和文本创建新笔记（自动添加 keep-mcp 标签）
• create_list：创建清单笔记
• update_note：更新笔记的标题和文本
• add_list_item：向清单笔记添加项目
• update_list_item：更新清单项目的文本和勾选状态
• delete_list_item：删除清单项目

笔记状态工具

• set_note_color：设置笔记颜色（有效值：DEFAULT、RED、ORANGE、YELLOW、GREEN、TEAL、BLUE、CERULEAN、PURPLE、PINK、BROWN、GRAY）
• pin_note：置顶或取消置顶笔记
• archive_note：归档或取消归档笔记
• trash_note：将笔记移至回收站
• restore_note：恢复已移至回收站／已删除的笔记
• delete_note：将笔记标记为待删除

标签、协作者和媒体工具

• list_labels：列出标签
• create_label：创建标签
• delete_label：删除标签
• add_label_to_note：为笔记添加标签
• remove_label_from_note：从笔记中移除标签
• list_note_collaborators：列出笔记协作者的邮箱地址
• add_note_collaborator：向笔记添加协作者邮箱地址
• remove_note_collaborator：从笔记中移除协作者邮箱地址
• list_note_media：列出笔记的媒体文件（含媒体链接）
• download_media：通过已验证的会话将笔记媒体（图片、绘图、音频）下载到本地目录（原始媒体链接对普通 HTTP 客户端会返回 403）

默认情况下，所有具有破坏性和修改性质的操作都仅限于由 MCP 服务创建的笔记（即带有 keep-mcp 标签的笔记）。将 UNSAFE_MODE 设为 true 可绕过此限制。

"env": {
  ...
  "UNSAFE_MODE": "true"
}

本地开发（uv + make）

如果你更喜欢 JS 风格的工作流（npm i、npm start），请使用附带的 Makefile：

make install   # like npm i
make start     # like npm start
make test
make lint

使用凭据运行真实账号冒烟测试：

GOOGLE_EMAIL="[email protected]" \
GOOGLE_MASTER_TOKEN="..." \
make smoke

等效的直接 uv 命令（不使用 make）：

UV_CACHE_DIR=/tmp/uv-cache uv venv --python 3.11 .venv
UV_CACHE_DIR=/tmp/uv-cache uv pip install --python .venv/bin/python -e .
UV_CACHE_DIR=/tmp/uv-cache uv run --no-sync --python .venv/bin/python -m server

测试

单元测试（默认）

项目在 tests/ 下包含一套轻量级单元测试。

它会验证：

• 笔记和列表对象的笔记序列化结构（包括标签、协作者、媒体和列表项）
• 修改安全行为（keep-mcp 标签要求和 UNSAFE_MODE=true 覆盖设置）
• 使用模拟的 Keep 客户端对象测试 src/server/cli.py 中的 MCP 工具行为（工具正常路径和关键错误路径）

在本地运行：

make test

针对真实 Keep 账户的冒烟测试

为进一步确认，可使用专用测试账户运行基本的生命周期冒烟测试：

GOOGLE_EMAIL="[email protected]" \
GOOGLE_MASTER_TOKEN="..." \
make smoke

该测试会：

• 创建笔记
• 更新笔记
• 固定／取消固定
• 归档／取消归档
• 移至回收站／恢复
• 删除

此脚本用于手动验证，不会在 CI 中运行。

CI 检查

GitHub Actions 会在每个拉取请求上运行，并执行：

• lint（ruff check .）
• 带覆盖率的单元测试（pytest -q --cov=src/server --cov-report=term-missing --cov-fail-under=70）
• 字节码检查（python -m compileall src）

发布

合并到 main 后自动发布（GitHub Actions）

此仓库包含位于 .github/workflows/release.yml 的发布工作流，每次推送到 main 时都会运行（包括已合并的拉取请求）。

它会：

• 检查上一个发布标签（vX.Y.Z）之后的提交
• 根据 Conventional Commit 类型计算下一个语义化版本
• 没有可发布的提交类型时跳过发布
• 运行 lint 和单元测试
• 构建 dist/*
• 发布到 PyPI
• 使用生成的说明创建 GitHub 发布版本／标签 v<computed-version>

版本升级规则：

• major：提交主题带有 !（例如：feat!: 或 fix(api)!:），或提交正文包含 BREAKING CHANGE
• minor：feat:
• patch：fix:、perf:、revert:
• 不发布：docs:、chore:、ci:、test:、refactor:（除非该提交标记为破坏性变更）

必需的仓库密钥：

• PYPI_API_TOKEN：PyPI API 令牌（建议的范围：仅限此项目）

手动发布

要手动发布到 PyPI：

1. 更新 pyproject.toml 中的版本
2. 构建软件包：

   pipx run build
   

3. 上传到 PyPI：

   pipx run twine upload --repository pypi dist/*
   

在本地通过 MCP 客户端运行

如果希望客户端从本地检出版本运行此服务，而不是从 PyPI 安装，此方式会很有用。

1. 创建本地虚拟环境并以可编辑模式安装：

cd /ABSOLUTE/PATH/TO/keep-mcp
make install

2. 将服务添加到 MCP 客户端配置中。

config.toml 客户端（Codex、Goose 等）

[mcp_servers.keep_mcp]
command = "make"
args = ["-C", "/ABSOLUTE/PATH/TO/keep-mcp", "start"]

[mcp_servers.keep_mcp.env]
GOOGLE_EMAIL = "[email protected]"
GOOGLE_MASTER_TOKEN = "your-master-token"
UNSAFE_MODE = "false"

JSON mcpServers 客户端（Claude Desktop、Cursor、Cline 等）

{
  "mcpServers": {
    "keep-mcp-local": {
      "command": "make",
      "args": ["-C", "/ABSOLUTE/PATH/TO/keep-mcp", "start"],
      "env": {
        "GOOGLE_EMAIL": "[email protected]",
        "GOOGLE_MASTER_TOKEN": "your-master-token",
        "UNSAFE_MODE": "false"
      }
    }
  }
}

替代方式（不使用 make）：

[mcp_servers.keep_mcp]
command = "uv"
args = [
  "--directory", "/ABSOLUTE/PATH/TO/keep-mcp",
  "run", "--no-sync", "--python", ".venv/bin/python",
  "-m", "server"
]

注意：

• 从 MCP 客户端启动前，先运行一次 make install。
• 只需提供仓库根目录路径（无需绝对的 /.venv/bin/python 路径）。
• 确保 make 和 uv 位于 PATH 中。
• 更新配置文件后，重启 MCP 客户端。
• UNSAFE_MODE 是可选项；除非明确要修改非 keep-mcp 笔记，否则请保持为 "false"。

故障排除

• 如果遇到 "DeviceManagementRequiredOrSyncDisabled"，请检查 https://admin.google.com/ac/devices/settings/general，并启用 "Turn off mobile management (Unmanaged)"