Google Tasks MCP Server
robot-apocalypse/gtasks-mcp
Gerencie Google Tasks via Claude com auto-hospedagem segura
Ver no GitHubServidor MCP auto-hospedado que integra Google Tasks com Claude, permitindo leitura e gerenciamento de tarefas via linguagem natural. Usa autenticação OAuth 2.0, armazenamento criptografado de tokens e Tailscale Funnel para exposição segura sem configuração de proxy reverso.
Instalação
npx convez-ai robot-apocalypse/gtasks-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de tarefas pessoais através de conversa com Claude
- Sincronização de tarefas em infraestrutura privada sem expor portas
- CRUD completo de Google Tasks via ferramentas MCP
- Integração de produtividade em fluxo de trabalho com IA
Veredito

Solução técnica robusta para quem já domina Docker, Tailscale e OAuth. Perfeita para auto-hospedagem segura, mas exige setup complexo e infraestrutura própria — não é plug-and-play.
README
A tradução para o português deste README ainda está na fila.
gtasks-mcp
A self-hosted Model Context Protocol server for Google Tasks. Lets Claude read and manage your tasks via natural language.
Features
- Full Google Tasks CRUD via 5 MCP tools
- Google OAuth 2.0 authentication
- Encrypted token storage (AES-256-GCM)
- HTTP Streamable transport — works with Claude.ai remote connectors
- Tailscale Funnel for secure public exposure — no reverse proxy needed
- Docker + docker-compose, auto-updates via Watchtower
How It Works
The server runs as a Docker container on your home server. A Tailscale sidecar container authenticates to your tailnet and exposes the server over Tailscale Funnel — a feature that makes your server reachable at a stable public HTTPS URL (https://gtasks-mcp.your-tailnet.ts.net) without opening firewall ports or configuring a reverse proxy.
Claude.ai connects to that URL to call the MCP tools. Port 3000 is never exposed to the host — it's only reachable within the shared Docker network namespace.
Prerequisites
- A home server running Docker
- A Tailscale account (free tier works)
- A Google account
Setup
1. Enable Tailscale Funnel
Funnel must be enabled for your tailnet before it will work.
- Go to Tailscale Admin → DNS and enable HTTPS Certificates
- Go to Tailscale Admin → Access Controls and add Funnel to your policy:
"nodeAttrs": [
{
"target": ["*"],
"attr": ["funnel"]
}
]
2. Get a Tailscale Auth Key
Go to Tailscale Admin → Settings → Keys and generate an auth key.
- Check Reusable and set no expiry (recommended for a server that may restart)
- Copy the key — you'll add it to
.envasTS_AUTHKEY
The Tailscale container will authenticate with this key and register as gtasks-mcp in your tailnet (set by hostname: in docker-compose.yml). Your server will then be reachable at https://gtasks-mcp.your-tailnet.ts.net.
3. Get Google OAuth Credentials
- Open Google Cloud Console and create a project
- Enable the Tasks API (APIs & Services → Enable APIs → search "Tasks API")
- Go to APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID
- Application type: Web application
- Authorized redirect URI:
https://gtasks-mcp.your-tailnet.ts.net/callback - Copy your Client ID and Client Secret
4. Configure
cp .env.example .env
Edit .env — replace every placeholder:
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=https://gtasks-mcp.your-tailnet.ts.net/callback
ENCRYPTION_SECRET=$(openssl rand -base64 32)
TS_AUTHKEY=tskey-auth-xxxx
5. Run
docker compose up -d
The Tailscale container starts, authenticates to your tailnet, and begins serving. The gtasks-mcp container starts and is reachable only through the Tailscale sidecar.
Check that it's up:
docker compose logs tailscale # should show "Connected."
docker compose logs gtasks-mcp # should show the port it's listening on
6. Authorize with Google
Open https://gtasks-mcp.your-tailnet.ts.net/auth in your browser and complete the Google sign-in. You'll see "Connected!" when done.
Your tokens are stored encrypted in ./data/tokens.json and will survive container restarts.
7. Add to Claude.ai
Go to Claude.ai → Settings → Connectors → Add Custom Connector:
- Name: Google Tasks
- URL:
https://gtasks-mcp.your-tailnet.ts.net/mcp
Click Connect. Claude will open the Google OAuth flow and your tasks will be available immediately.
Tailscale Serve Config
The included tailscale-serve.json tells Tailscale to:
- Terminate HTTPS on port 443 using your tailnet's automatically-provisioned certificate
- Proxy all requests to
http://127.0.0.1:3000(the app, via the shared network namespace) - Enable Funnel so the URL is reachable from the public internet (not just your tailnet)
You don't need to modify this file.
Auto-Updates (Watchtower)
The watchtower service in docker-compose.yml automatically pulls updated images for tailscale and gtasks-mcp every night at 3 AM and restarts them if a new version is available. It is scoped to this stack via the com.centurylinklabs.watchtower.scope=gtasks-mcp label.
MCP Tools
| Tool | Description |
|---|---|
list_task_lists | Get all your Google Task lists |
list_tasks | Get tasks in a list (optionally include completed) |
create_task | Create a task with title, notes, and due date |
update_task | Update a task or mark it complete/incomplete |
delete_task | Permanently delete a task |
Development
npm install
cp .env.example .env # fill in real values
npm run dev # starts on http://localhost:3000
npm test # run unit tests
npm run build # compile TypeScript to dist/
Environment Variables
| Variable | Required | Description |
|---|---|---|
GOOGLE_CLIENT_ID | Yes | OAuth 2.0 client ID from GCP |
GOOGLE_CLIENT_SECRET | Yes | OAuth 2.0 client secret from GCP |
GOOGLE_REDIRECT_URI | Yes | Must match GCP console exactly |
ENCRYPTION_SECRET | Yes | Min 32 chars — used for AES-256-GCM token encryption |
TS_AUTHKEY | Yes | Tailscale auth key for the sidecar container |
PORT | No | HTTP port (default: 3000) |
Architecture
# OAuth 2.0 Authorization Server (for Claude.ai connector registration)
GET /.well-known/oauth-authorization-server → AS metadata (RFC 8414)
GET /.well-known/oauth-protected-resource → Protected resource metadata (RFC 9728)
GET /.well-known/oauth-protected-resource/mcp → Same, path-aware variant
POST /register → Dynamic client registration (RFC 7591)
GET /authorize → PKCE authorization endpoint
POST /token → Token endpoint
# Google OAuth (one-time setup to link your Google account)
GET /auth → Redirect to Google OAuth consent screen
GET /callback → Exchange auth code for tokens, encrypt and save
# Server
GET /health → 200 OK
ALL /mcp → MCP Streamable HTTP endpoint (requires Bearer token)
When you add the connector in Claude.ai, it automatically discovers the OAuth endpoints, registers itself, and walks you through Google sign-in — no manual steps beyond clicking Connect.
Google tokens are stored encrypted in data/tokens.json on a bind-mounted volume. They are loaded and refreshed automatically on each request — you should never need to re-authorize unless you explicitly revoke access in your Google account.
License
MIT