Google Keep MCP

谷歌保留MCP服务器

使用Claude代码

使用此MCP服务器和附带的Claude Code斜线命令，您可以在编码会话中直接获得轻量级的任务管理工作流。

Slash命令

复制 .claude/commands/ 到 ~/.claude/commands/ 使这些在全球范围内可用，并将标签约定添加到您的全球范围内 CLAUDE.md （见下文）。

# Install slash commands globally
mkdir -p ~/.claude/commands
cp .claude/commands/* ~/.claude/commands/

标签惯例

这些命令依赖于中定义的标签架构 ~/.claude/CLAUDE.md:

• **state_*** --任务状态，互斥： state_todo, state_doing, state_blocking, state_waiting
• **project_*** --注释所属的项目（一个注释可以有多个）
• time_YYYY_MM --创建注释的月份，自动应用
• **topic_*** --知识领域 /capture 备注（例如基础设施、法学硕士、工具、职业）

典型会话

/next                                    # see all active tasks
/next 
                          # filter to a single project
/doing 1a2b3c4d5e6f                      # start a task
/progress 1a2b3c4d5e6f initial spike done, moving to impl  # log progress
/block 1a2b3c4d5e6f can't proceed, env broken  # self-blocked
/waiting 1a2b3c4d5e6f alice reviewing the PR    # handed off
/capture decided to use SSE over polling # save a decision
/done 1a2b3c4d5e6f complexity too high, shelved  # complete with note
/catchup 
 --last 7d             # weekly report for a project
/explore                          # browse knowledge base by topic
/tidy                                    # fix any notes with missing labels

特性

• 18个MCP工具 包括笔记、清单、标签、搜索、笔记属性和同步
• 基于令牌的身份验证（不推荐使用密码登录）
• 可选状态缓存，可实现更快的重启
• 所有工具的结构化Pydantic输出模型

需求

• Python 3.11+
• 具有Keep访问权限的Google帐户
• Google主令牌（见下文）

获取主令牌

谷歌限制了基于密码的直接身份验证，因此获取主令牌需要基于浏览器的流程。最可靠的方法是：

1. 打开 https://accounts.google.com/EmbeddedSetup 在浏览器中完全登录（如果启用，包括两步验证）
2. 登录后，打开DevTools→ 应用 （Chrome）或 存储 （火狐浏览器）→ Cookie→ accounts.google.com
3. 查找名为的cookie oauth_token （值以开头 oauth2_4/ 或 oauth2_1/)并复制它
4. 确保您已安装gpsoauth 2.0.0+(pip install --upgrade gpsoauth)，然后运行：

python3 -c "
import gpsoauth, getpass
email = input('Google email: ')
oauth_token = getpass.getpass('oauth_token cookie value: ')
result = gpsoauth.exchange_token(email, oauth_token, '0123456789abcdef')
print(result.get('Token', result))
"

结果 aas_et/... 字符串是你的 GOOGLE_MASTER_TOKEN.

有关更多上下文和替代方法，请参阅 kiwiz/gkeepapi#171.

安装

git clone 
cd google-keep-mcp
uv pip install -e .

或者直接用pip安装：

pip install -e .

配置

复制 .env.example 到 .env 并填写您的凭据：

cp .env.example .env

跑步

GOOGLE_EMAIL=you@gmail.com GOOGLE_MASTER_TOKEN=aas_et/... google-keep-mcp

或者用a .env 当前目录中的文件：

google-keep-mcp

Claude桌面集成

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "google-keep": {
      "command": "/path/to/google-keep-mcp/.venv/bin/google-keep-mcp",
      "env": {
        "GOOGLE_EMAIL": "your@gmail.com",
        "GOOGLE_MASTER_TOKEN": "aas_et/..."
      }
    }
  }
}

在macOS上： ~/Library/Application Support/Claude/claude_desktop_config.json 在Windows上： %APPDATA%\Claude\claude_desktop_config.json

Claude代码集成

添加到MCP设置(.claude/settings.json 或 ~/.claude/settings.json):

{
  "mcpServers": {
    "google-keep": {
      "command": "/path/to/google-keep-mcp/.venv/bin/google-keep-mcp",
      "env": {
        "GOOGLE_EMAIL": "your@gmail.com",
        "GOOGLE_MASTER_TOKEN": "aas_et/..."
      }
    }
  }
}

然后复制斜线命令和全局CLAUDE.md，如中所述 使用Claude代码.

MCP检验员测试

mcp dev src/google_keep_mcp/server.py

可用工具

发展

# Install with dev dependencies (includes pre-commit, ruff)
uv pip install -e ".[dev]"

# Install pre-commit hooks (run once after cloning)
.venv/bin/pre-commit install

# Run tests
.venv/bin/python3 -m pytest tests/ -v

# Run all pre-commit hooks manually
.venv/bin/pre-commit run --all-files

预提交钩子自动运行 git commit。如果ruff进行自动修复更改，则提交将被阻止——重新暂存修改后的文件(git add -u)并再次承诺。如果gitleaks检测到秘密，请在重试前将其删除。

备注

• delete_note 将笔记移动到垃圾桶（Google Keep不会通过API公开硬删除）
• 所有突变呼叫 keep.sync() 自动将更改持久化到谷歌的服务器
• 在使用缓存文件启动时，服务器会执行增量同步；如果没有缓存文件，则执行完全同步
• 使用 sync 工具（或 /next, /catchup 自动调用它）以拉取其他客户端（移动应用程序、网络）所做的更改