AI导哈

任务管理系统

一个基于Google Keep的个人任务和知识管理系统，通过AI助手和斜杠命令实现自动化笔记管理。

  • by staryxchen
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 staryxchen/google-keep-mcp

使用说明

谷歌保留MCP服务器

A. 模型上下文协议 将Google Keep转化为 无笔记个人任务与知识体系 AI助手。您可以通过一组斜线命令进行交互，而不是手动写笔记(/todo, /doing, /done, /capture, /next，…）处理所有簿记——创建笔记、转换状态、附加进度日志、归档已完成的工作——这样你就可以专注于实际工作。MCP层包裹 gkeepapi 用于结构化访问笔记、列表和标签，而顶部的命令和标签约定形成了一个完整的、有主见的工作流程。

使用Claude代码

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

Slash命令

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

# Install slash commands globally
mkdir -p ~/.claude/commands
cp .claude/commands/* ~/.claude/commands/
命令 用法 说明
/next /next [project] 列出按项目分组的所有活动任务；可选地筛选到单个项目（例如。 /next <project>)
/todo /todo <task description> 使用以下命令创建新任务注释 state_todo 标签
/doing /doing <note_id> 将任务转换为 state_doing
/progress /progress <note_id> [update] 附上带时间戳的进度条目；省略从对话历史自动生成的更新，以及 git log
/done /done [note_id] [completion note] 将已完成的任务存档；省略note_id以交互式地从自动生成摘要的任务中进行选择
/block /block <note_id> <reason> 将任务标记为自阻塞，将原因附加到注释正文
/waiting /waiting <note_id> <who/why> 将任务标记为等待其他人，将上下文附加到注释正文
/capture /capture <content> 保留一个想法、决定或发现
/catchup /catchup <project> [--last <N>d/w/m|--since <date>] 按状态总结项目笔记；为周报格式添加时间范围
/explore /explore [topic] 按主题浏览知识库；省略计数概述的主题
/tidy /tidy 扫描所有活动笔记中的标签/标题冲突，并以交互方式修复它们

标签惯例

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

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

典型会话

/next                                    # see all active tasks
/next <project>                          # 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 <project> --last 7d             # weekly report for a project
/explore <topic>                         # 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 <repo-url>
cd google-keep-mcp
uv pip install -e .

或者直接用pip安装：

pip install -e .

配置

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

cp .env.example .env
变量 必填 描述
GOOGLE_EMAIL 是 您的Google帐户电子邮件
GOOGLE_MASTER_TOKEN 是 来自gpsoauth的主令牌
KEEP_CACHE_FILE 否 JSON缓存路径，可实现更快的重启
LOG_LEVEL 没有 DEBUG, INFO, WARNING, ERROR （默认值： INFO)

跑步

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

可用工具

工具 说明
list_notes 列出带有可选过滤器（存档、固定、颜色、标签）的笔记
get_note 按ID获取备注
create_note 创建文字注释
update_note 更新笔记标题、文本、颜色、固定或存档状态
delete_note 将便条移至垃圾箱
untrash_note 从回收站还原笔记
archive_note 存档或取消存档笔记
pin_note 固定或取消固定便条
search_notes 在标题和正文之间进行全文搜索
create_list 创建一个包含可选项目的清单
update_list_items 添加、更新、选中或取消选中列表中的项目
sort_list_items 按字母顺序对清单项目进行排序
list_labels 列出所有标签
create_label 创建新标签
add_label_to_note 在笔记上贴标签
remove_label_from_note 从笔记中删除标签
delete_label 从帐户中永久删除标签
sync 与Google Keep服务器同步以获取最新更改

发展

# 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 自动调用它）以拉取其他客户端（移动应用程序、网络）所做的更改

相关 MCP