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 を使用します。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

make を使わずに uv コマンドを直接実行する場合：

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 へのプッシュ（マージされた PR を含む）のたびに実行されます。

以下を実行します。

• 最後のリリースタグ（vX.Y.Z）以降のコミットを調べる
• Conventional Commit の種類から次のセマンティックバージョンを算出する
• リリース対象となるコミットの種類がない場合は公開をスキップする
• lint とユニットテストを実行する
• dist/* をビルドする
• PyPI に公開する
• 生成したリリースノートとともに GitHub リリース／タグ v<computed-version> を作成する

バージョン更新のルール：

• メジャー：! を含むコミットの件名（例：feat!: または fix(api)!:）、または本文に BREAKING CHANGE を含むコミット
• マイナー：feat:
• パッチ：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)」を有効にしてください。