Servidor MCP de Google Keep | Awesome MCP Servers

keep-mcp

Servidor MCP para Google Keep

keep-mcp

Cómo usar

Añade el servidor MCP a tus servidores 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"
      }
    }
  }

O con 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"
      }
    }
  }

Añade tus credenciales:

GOOGLE_EMAIL: La dirección de correo electrónico de tu cuenta de Google
GOOGLE_MASTER_TOKEN: El token maestro de tu cuenta de Google

Obtener un token maestro de Google

keep-mcp utiliza gkeepapi, que se conecta a Google Keep a través de una API privada no oficial. Un token maestro de Google tiene acceso completo a tu cuenta. Trátalo como una contraseña y nunca lo confirmes ni lo compartas.

Utiliza el intercambio de tokens asistido por navegador documentado por gpsoauth. Elige cómo quieres ejecutar el intercambio:

Python local: Sigue el flujo alternativo de gpsoauth.
Docker: Sigue las instrucciones de "Obtención de un token maestro" de gkeepapi. Esto ejecuta el mismo intercambio sin requerir una instalación local de Python.

Ambas opciones requieren el navegador oauth_token descrito en la documentación de gpsoauth.

Las instrucciones más antiguas pueden pedir tu contraseña de Google o una contraseña de aplicación y llamar a perform_master_login(). Ese flujo no es fiable y puede devolver BadAuthentication. Utiliza el flujo asistido por navegador anterior en su lugar.

Características

Herramientas de consulta y lectura

find: Buscar notas (sin distinción de mayúsculas/minúsculas por defecto) con filtros opcionales para etiquetas, colores, fijadas, archivadas, en la papelera, rangos de fechas de creación/actualización (ISO 8601, UTC) y un límite de resultados
get_note: Obtener una sola nota por ID

Herramientas de creación y actualización

create_note: Crear una nueva nota con título y texto (añade automáticamente la etiqueta keep-mcp)
create_list: Crear una nota de lista de verificación
update_note: Actualizar el título y el texto de una nota
add_list_item: Añadir un elemento a una nota de lista de verificación
update_list_item: Actualizar el texto y el estado de marcado de un elemento de lista de verificación
delete_list_item: Eliminar un elemento de lista de verificación

Herramientas de estado de notas

set_note_color: Establecer el color de una nota (valores válidos: DEFAULT, RED, ORANGE, YELLOW, GREEN, TEAL, BLUE, CERULEAN, PURPLE, PINK, BROWN, GRAY)
pin_note: Fijar o desfijar una nota
archive_note: Archivar o desarchivar una nota
trash_note: Mover una nota a la papelera
restore_note: Restaurar una nota en la papelera/eliminada
delete_note: Marcar una nota para su eliminación

Herramientas de etiquetas, colaboradores y medios

list_labels: Listar etiquetas
create_label: Crear una etiqueta
delete_label: Eliminar una etiqueta
add_label_to_note: Añadir una etiqueta a una nota
remove_label_from_note: Quitar una etiqueta de una nota
list_note_collaborators: Listar los correos electrónicos de los colaboradores de una nota
add_note_collaborator: Añadir un correo electrónico de colaborador a una nota
remove_note_collaborator: Quitar un correo electrónico de colaborador de una nota
list_note_media: Listar los blobs de medios de una nota (con enlaces de medios)

Por defecto, todas las operaciones destructivas y de modificación están restringidas a notas que fueron creadas por el servidor MCP (es decir, que tienen la etiqueta keep-mcp). Establece UNSAFE_MODE a true para omitir esta restricción.

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

Desarrollo local (uv + make)

Si prefieres un flujo de trabajo estilo JS (npm i, npm start), usa el Makefile incluido:

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

Ejecuta la prueba de humo con cuenta real usando credenciales:

GOOGLE_EMAIL="you@example.com" \
GOOGLE_MASTER_TOKEN="..." \
make smoke

Comandos directos equivalentes de uv (sin 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

Pruebas

Pruebas unitarias (por defecto)

El proyecto incluye un conjunto de pruebas unitarias ligero en tests/.

Valida:

la forma de serialización de notas para objetos de nota y lista (incluyendo etiquetas, colaboradores, medios y elementos de lista)
el comportamiento de seguridad de modificación (requisito de etiqueta keep-mcp y anulación de UNSAFE_MODE=true)
el comportamiento de las herramientas MCP en src/server/cli.py usando objetos de cliente Keep simulados (rutas felices de herramientas y rutas de error clave)

Ejecuta localmente:

make test

Prueba de humo contra una cuenta real de Keep

Para mayor confianza, ejecuta una prueba de humo básica del ciclo de vida contra una cuenta de prueba dedicada:

GOOGLE_EMAIL="you@example.com" \
GOOGLE_MASTER_TOKEN="..." \
make smoke

Lo que hace:

crear nota
actualizar nota
fijar/desfijar
archivar/desarchivar
papelera/restaurar
eliminar

Este script está pensado para verificación manual y no se ejecuta en CI.

Comprobaciones de CI

GitHub Actions se ejecuta en cada pull request y ejecuta:

lint (ruff check .)
pruebas unitarias con cobertura (pytest -q --cov=src/server --cov-report=term-missing --cov-fail-under=70)
verificación de bytecode (python -m compileall src)

Publicación

Publicación automática al fusionar en `main` (GitHub Actions)

Este repositorio incluye un flujo de trabajo de lanzamiento en .github/workflows/release.yml que se ejecuta en cada push a main (incluyendo PRs fusionados).

Hará lo siguiente:

inspeccionar los commits desde la última etiqueta de lanzamiento (vX.Y.Z)
calcular la siguiente versión semántica a partir de los tipos de Conventional Commit
omitir la publicación cuando no haya tipos de commit publicables
ejecutar lint y pruebas unitarias
construir dist/*
publicar en PyPI
crear un lanzamiento/etiqueta de GitHub v<computed-version> con notas generadas

Reglas de incremento de versión:

mayor: asunto del commit con ! (ejemplo: feat!: o fix(api)!:) o cuerpo del commit que contenga BREAKING CHANGE
menor: feat:
parche: fix:, perf:, revert:
sin lanzamiento: docs:, chore:, ci:, test:, refactor: (a menos que el commit esté marcado como ruptura)

Secreto de repositorio requerido:

PYPI_API_TOKEN: un token de API de PyPI (alcance recomendado: solo este proyecto)

Publicación manual

Para publicar manualmente en PyPI:

Actualiza la versión en pyproject.toml
Construye el paquete:
```
pipx run build
```

Sube a PyPI:

pipx run twine upload --repository pypi dist/*

Ejecutar localmente con clientes MCP

Esto es útil cuando quieres que un cliente ejecute este servidor desde tu checkout local en lugar de PyPI.

Crea un virtualenv local e instala en modo editable:

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

Añade el servidor a la configuración de tu cliente MCP.

Clientes `config.toml` (Codex, Goose, etc.)

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

[mcp_servers.keep_mcp.env]
GOOGLE_EMAIL = "you@example.com"
GOOGLE_MASTER_TOKEN = "your-master-token"
UNSAFE_MODE = "false"

Clientes JSON `mcpServers` (Claude Desktop, Cursor, Cline, etc.)

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

Alternativa (sin make):

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

Notas:

Ejecuta make install una vez antes de iniciar desde un cliente MCP.
Solo se requiere la ruta raíz del repositorio (sin ruta absoluta de /.venv/bin/python).
Asegúrate de que make y uv estén en tu PATH.
Reinicia tu cliente MCP después de actualizar los archivos de configuración.
UNSAFE_MODE es opcional; mantenlo en "false" a menos que quieras explícitamente modificar notas que no sean de keep-mcp.

Solución de problemas

Si obtienes "DeviceManagementRequiredOrSyncDisabled", revisa https://admin.google.com/ac/devices/settings/general y activa "Desactivar gestión móvil (No administrado)"

Google Keep

Documentación

keep-mcp

Cómo usar

Obtener un token maestro de Google

Características

Herramientas de consulta y lectura

Herramientas de creación y actualización

Herramientas de estado de notas

Herramientas de etiquetas, colaboradores y medios

Desarrollo local (uv + make)

Pruebas

Pruebas unitarias (por defecto)

Prueba de humo contra una cuenta real de Keep

Comprobaciones de CI

Publicación

Publicación automática al fusionar en main (GitHub Actions)

Publicación manual

Ejecutar localmente con clientes MCP

Clientes config.toml (Codex, Goose, etc.)

Clientes JSON mcpServers (Claude Desktop, Cursor, Cline, etc.)

Solución de problemas

Publicación automática al fusionar en `main` (GitHub Actions)

Clientes `config.toml` (Codex, Goose, etc.)

Clientes JSON `mcpServers` (Claude Desktop, Cursor, Cline, etc.)