durable-objects-mcp

Consulte seus Cloudflare Durable Objects a partir do Claude Code, Cursor e outros clientes de IA.

Documentação

🟧 durable-objects-mcp

Rick Rubin knows

Servidor MCP não oficial para consultar o armazenamento SQLite do Cloudflare Durable Object a partir de clientes de IA (Claude Code, Cursor, Windsurf, etc.). Oferece aos clientes de IA acesso estruturado e somente leitura ao seu armazenamento de DOs. Conecte uma vez, descubra tabelas, execute consultas.

🤔 Por quê

Durable Objects armazenam estado em bancos de dados SQLite privados, sem acesso programático a consultas — apenas o Data Studio no painel. Construímos isso enquanto trabalhávamos no Spawnbase porque navegar manualmente por milhares de instâncias de DOs não é viável.

TODO: A melhor versão desta ferramenta é uma que não precise existir. Adoraríamos que a Cloudflare lançasse acesso nativo e seguro para consultas ao armazenamento de DOs. Até lá, isto preenche a lacuna.

⚙️ O que ele possibilita

You (while sipping coffee): "What tables does the AIAgent DO have for user abc123?"

→ describe_schema({ class_name: "AIAgent", name: "abc123" })

  _cf_KV           — key TEXT, value BLOB
  cf_agents_state  — id TEXT, data BLOB
  cf_agents_messages — id TEXT, role TEXT, content TEXT, created_at INTEGER
  ...

You (after the second sip): "Show me the last 5 messages"

→ query({ class_name: "AIAgent", name: "abc123",
          sql: "SELECT role, content FROM cf_agents_messages ORDER BY created_at DESC LIMIT 5" })

  role       | content
  -----------|----------------------------------
  user       | Deploy the workflow to production
  assistant  | I'll deploy workflow wf_a8c3...
  ...

Um Cloudflare Worker independente que faz bind aos seus namespaces de DOs via script_name e chama um método RPC query() em cada instância de DO. Autenticação via Cloudflare Access (OAuth).

🔒 Segurança

Aviso: Durable Objects podem armazenar dados sensíveis — tokens de sessão, PII, registros de pagamento, histórico de conversas. Antes de implantar, revise o que seus DOs contêm, faça bind apenas dos namespaces que você precisa e restrinja sua política de Cloudflare Access de acordo. Se você atende usuários finais, certifique-se de que seus termos de serviço cubram esse tipo de acesso a dados.

Levamos a segurança a sério ao construir isso. Veja o que implementamos:

Cloudflare Access (OAuth) — toda a autenticação acontece na borda antes de a requisição chegar ao Worker. Os JWTs são verificados contra o JWKS do CF Access (assinatura, algoritmo, expiração). PKCE (somente S256) é aplicado no lado do cliente MCP. Revogar um usuário no seu provedor de identidade corta a sessão MCP dele no próximo refresh de token.
Somente leitura por design — um guard de SQL no lado do servidor rejeita qualquer coisa que não seja SELECT, PRAGMA, EXPLAIN ou WITH antes de chegar ao DO. Todas as instruções de escrita são bloqueadas no nível do servidor MCP.
Sem acesso público aos DOs — a chamada RPC query() usa service bindings da Cloudflare (script_name), que permanecem inteiramente dentro da rede interna da Cloudflare. Não há endpoint HTTP público para os DOs. O servidor MCP é a única forma de acesso.
Escopo explícito de namespaces — apenas classes de DOs com bindings em wrangler.jsonc são detectáveis e consultáveis. Nada é exposto por padrão.

🛠️ Ferramentas

Ferramenta	O que faz
`list_classes`	Lista classes de DOs consultáveis configuradas na sua implantação
`describe_schema`	Retorna tabelas e colunas de uma instância de DO
`execute_read_query`	Executa SQL somente leitura em uma instância de DO

🚀 Configuração

1. Adicione um método `query()` às suas classes de DOs

Cada classe de DO que você deseja consultar precisa deste método:

query(sql: string) {
  const cursor = this.ctx.storage.sql.exec(sql)
  return { columns: cursor.columnNames, rows: [...cursor.raw()] }
}

O guard de SQL do servidor MCP bloqueia todas as instruções não-SELECT antes que cheguem ao DO.

2. Clone e configure

git clone https://github.com/spawnbase/durable-objects-mcp.git
cd durable-objects-mcp
pnpm install

Edite wrangler.jsonc — adicione bindings de DOs apontando para o seu Worker:

"durable_objects": {
  "bindings": [
    { "name": "DO_MCP_AGENT", "class_name": "DOMcpAgent" },
    {
      "name": "AI_AGENT",
      "class_name": "AIAgent",
      "script_name": "your-worker-name"
    }
  ]
}

Qualquer binding de DO (exceto DO_MCP_AGENT) é automaticamente consultável — nenhuma configuração adicional é necessária.

3. Configure a autenticação (Cloudflare Access)

Siga o guia Proteja servidores MCP com Access for SaaS:

Crie um aplicativo SaaS em Cloudflare One → Access → Applications
Selecione OIDC como protocolo de autenticação
Defina a URL de redirect para https://your-worker.workers.dev/callback
Em Policies, adicione uma política de Access controlando quem pode se conectar (ex.: lista de e-mails, grupo do IdP)
Em Login methods, selecione quais provedores de identidade estão disponíveis (GitHub, Google, One-time PIN, etc.)
Copie o Client ID e o Client Secret da configuração do aplicativo

Depois, defina os secrets:

wrangler secret put ACCESS_TEAM             # your Zero Trust team name
wrangler secret put ACCESS_CLIENT_ID        # from the SaaS app
wrangler secret put ACCESS_CLIENT_SECRET    # from the SaaS app
wrangler secret put COOKIE_ENCRYPTION_KEY   # openssl rand -hex 32

4. Implante

wrangler deploy

5. Conecte seu cliente MCP

Na primeira conexão, você será autenticado via Cloudflare Access (pop-up do navegador). Depois disso, a sessão persiste.

Claude Code:

claude mcp add --transport http do-explorer https://your-worker.workers.dev/mcp

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "do-explorer": { "url": "https://your-worker.workers.dev/mcp" }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.do-explorer]
url = "https://your-worker.workers.dev/mcp"

Depois, execute codex mcp login do-explorer para autenticar.

OpenCode (opencode.json):

{
  "mcp": {
    "do-explorer": {
      "type": "remote",
      "url": "https://your-worker.workers.dev/mcp"
    }
  }
}

📋 Requisitos

5 minutos
Plano pago do Cloudflare Workers
Durable Objects com suporte a SQLite (data de compatibilidade 2024-04-03+)
Cloudflare Zero Trust (para autenticação)

📄 Licença

MIT

durable-objects-mcp

Documentação