Servidor MCP Google Keep | Awesome MCP Servers

keep-mcp

Servidor MCP para Google Keep

keep-mcp

Como usar

Adicione o servidor MCP aos seus 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"
      }
    }
  }

Ou com 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"
      }
    }
  }

Adicione suas credenciais:

GOOGLE_EMAIL: O endereço de e-mail da sua conta Google
GOOGLE_MASTER_TOKEN: O token mestre da sua conta Google

Obter um token mestre do Google

keep-mcp usa gkeepapi, que se conecta ao Google Keep por meio de uma API privada não oficial. Um token mestre do Google tem acesso total à sua conta. Trate-o como uma senha e nunca o envie ou compartilhe.

Use a troca de token assistida pelo navegador documentada por gpsoauth. Escolha como deseja executar a troca:

Python local: Siga o fluxo alternativo de gpsoauth.
Docker: Siga as instruções de gkeepapi "Obtaining a Master Token". Isso executa a mesma troca sem exigir uma instalação local de Python.

Ambas as opções exigem o navegador oauth_token descrito na documentação do gpsoauth.

Instruções mais antigas podem pedir sua senha do Google ou uma senha de aplicativo e chamar perform_master_login(). Esse fluxo não é confiável e pode retornar BadAuthentication. Use o fluxo assistido pelo navegador acima em vez disso.

Recursos

Ferramentas de consulta e leitura

find: Pesquisar notas (sem diferenciar maiúsculas/minúsculas por padrão) com filtros opcionais para rótulos, cores, fixadas, arquivadas, na lixeira, intervalos de data de criação/atualização (ISO 8601, UTC) e um limite de resultados
get_note: Obter uma única nota por ID

Ferramentas de criação e atualização

create_note: Criar uma nova nota com título e texto (adiciona automaticamente o rótulo keep-mcp)
create_list: Criar uma nota de lista de verificação
update_note: Atualizar o título e o texto de uma nota
add_list_item: Adicionar um item a uma nota de lista de verificação
update_list_item: Atualizar o texto e o estado de marcação de um item da lista de verificação
delete_list_item: Excluir um item da lista de verificação

Ferramentas de estado da nota

set_note_color: Definir a cor de uma nota (valores válidos: DEFAULT, RED, ORANGE, YELLOW, GREEN, TEAL, BLUE, CERULEAN, PURPLE, PINK, BROWN, GRAY)
pin_note: Fixar ou desafixar uma nota
archive_note: Arquivar ou desarquivar uma nota
trash_note: Mover uma nota para a lixeira
restore_note: Restaurar uma nota na lixeira/excluída
delete_note: Marcar uma nota para exclusão

Ferramentas de rótulos, colaboradores e mídia

list_labels: Listar rótulos
create_label: Criar um rótulo
delete_label: Excluir um rótulo
add_label_to_note: Adicionar um rótulo a uma nota
remove_label_from_note: Remover um rótulo de uma nota
list_note_collaborators: Listar e-mails de colaboradores de uma nota
add_note_collaborator: Adicionar um e-mail de colaborador a uma nota
remove_note_collaborator: Remover um e-mail de colaborador de uma nota
list_note_media: Listar blobs de mídia de uma nota (com links de mídia)

Por padrão, todas as operações destrutivas e de modificação são restritas a notas que foram criadas pelo servidor MCP (ou seja, que têm o rótulo keep-mcp). Defina UNSAFE_MODE como true para ignorar essa restrição.

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

Desenvolvimento local (uv + make)

Se você preferir um fluxo de trabalho no estilo JS (npm i, npm start), use o Makefile incluído:

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

Execute o teste de fumaça com conta real usando credenciais:

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

Comandos diretos equivalentes de uv (sem 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

Testes

Testes unitários (padrão)

O projeto inclui uma suíte de testes unitários leve em tests/.

Ela valida:

a forma de serialização de notas e objetos de lista (incluindo rótulos, colaboradores, mídia e itens de lista)
o comportamento de segurança de modificação (requisito do rótulo keep-mcp e substituição de UNSAFE_MODE=true)
o comportamento das ferramentas MCP em src/server/cli.py usando objetos de cliente Keep simulados (caminhos felizes das ferramentas e caminhos de erro principais)

Execute localmente:

make test

Teste de fumaça com uma conta Keep real

Para maior confiança, execute um teste de fumaça básico de ciclo de vida em uma conta de teste dedicada:

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

O que ele faz:

criar nota
atualizar nota
fixar/desafixar
arquivar/desarquivar
mover para a lixeira/restaurar
excluir

Este script é destinado à verificação manual e não é executado no CI.

Verificações de CI

O GitHub Actions é executado em cada pull request e executa:

lint (ruff check .)
testes unitários com cobertura (pytest -q --cov=src/server --cov-report=term-missing --cov-fail-under=70)
verificação de sanidade do bytecode (python -m compileall src)

Publicação

Publicação automática ao mesclar em `main` (GitHub Actions)

Este repositório inclui um fluxo de trabalho de lançamento em .github/workflows/release.yml que é executado em cada push para main (incluindo PRs mesclados).

Ele irá:

inspecionar os commits desde a última tag de lançamento (vX.Y.Z)
calcular a próxima versão semântica a partir dos tipos de Conventional Commit
pular a publicação quando não houver tipos de commit publicáveis
executar lint e testes unitários
compilar dist/*
publicar no PyPI
criar um release/tag do GitHub v<computed-version> com notas geradas

Regras de incremento de versão:

major: assunto do commit com ! (exemplo: feat!: ou fix(api)!:) ou corpo do commit contendo BREAKING CHANGE
minor: feat:
patch: fix:, perf:, revert:
sem lançamento: docs:, chore:, ci:, test:, refactor: (a menos que o commit seja marcado como breaking)

Segredo obrigatório do repositório:

PYPI_API_TOKEN: um token de API do PyPI (escopo recomendado: apenas este projeto)

Publicação manual

Para publicar manualmente no PyPI:

Atualize a versão em pyproject.toml
Compile o pacote:
```
pipx run build
```

Envie para o PyPI:

pipx run twine upload --repository pypi dist/*

Executar localmente com clientes MCP

Isso é útil quando você quer que um cliente execute este servidor a partir do seu checkout local em vez do PyPI.

Crie um virtualenv local e instale em modo editável:

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

Adicione o servidor à configuração do seu 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 (sem make):

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

Notas:

Execute make install uma vez antes de iniciar a partir de um cliente MCP.
Apenas o caminho raiz do repositório é necessário (sem caminho absoluto de /.venv/bin/python).
Garanta que make e uv estejam no seu PATH.
Reinicie seu cliente MCP após atualizar os arquivos de configuração.
UNSAFE_MODE é opcional; mantenha-o "false" a menos que você queira explicitamente modificar notas não keep-mcp.

Solução de problemas

Se você receber "DeviceManagementRequiredOrSyncDisabled", verifique https://admin.google.com/ac/devices/settings/general e ative "Turn off mobile management (Unmanaged)"

Google Keep

Documentação

keep-mcp

Como usar

Obter um token mestre do Google

Recursos

Ferramentas de consulta e leitura

Ferramentas de criação e atualização

Ferramentas de estado da nota

Ferramentas de rótulos, colaboradores e mídia

Desenvolvimento local (uv + make)

Testes

Testes unitários (padrão)

Teste de fumaça com uma conta Keep real

Verificações de CI

Publicação

Publicação automática ao mesclar em main (GitHub Actions)

Publicação manual

Executar localmente com clientes MCP

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

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

Solução de problemas

Publicação automática ao mesclar em `main` (GitHub Actions)

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

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