durable-objects-mcp

Consulta tus Cloudflare Durable Objects desde Claude Code, Cursor y otros clientes de IA.

Documentación

🟧 durable-objects-mcp

Rick Rubin knows

Servidor MCP no oficial para consultar el almacenamiento SQLite de Durable Objects de Cloudflare desde clientes de IA (Claude Code, Cursor, Windsurf, etc.). Proporciona a los clientes de IA acceso estructurado y de solo lectura a tu almacenamiento de DO. Conéctate una vez, descubre tablas, ejecuta consultas.

🤔 Por qué

Los Durable Objects almacenan estado en bases de datos SQLite privadas sin acceso de consulta programático — solo Data Studio en el panel de control. Construimos esto mientras trabajábamos en Spawnbase porque hacer clic manualmente a través de miles de instancias de DO no es viable.

TODO: La mejor versión de esta herramienta es una que no necesite existir. Nos encantaría que Cloudflare lanzara acceso de consulta nativo y seguro para el almacenamiento de DO. Hasta entonces, esto llena el vacío.

⚙️ Qué permite

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...
  ...

Un Worker de Cloudflare independiente que se vincula a tus namespaces de DO mediante script_name y llama a un método RPC query() en cada instancia de DO. Autenticación mediante Cloudflare Access (OAuth).

🔒 Seguridad

Advertencia: Los Durable Objects pueden almacenar datos sensibles — tokens de sesión, PII, registros de pago, historial de conversaciones. Antes de implementar, revisa qué contienen tus DOs, vincula solo los namespaces que necesites y restringe tu política de Cloudflare Access en consecuencia. Si atiendes a usuarios finales, asegúrate de que tus términos de servicio cubran este tipo de acceso a datos.

Nos tomamos la seguridad en serio al construir esto. Esto es lo que implementamos:

Cloudflare Access (OAuth) — toda la autenticación ocurre en el borde antes de que la solicitud llegue al Worker. Los JWT se verifican contra el JWKS de CF Access (firma, algoritmo, expiración). PKCE (solo S256) se aplica en el lado del cliente MCP. Revocar a un usuario en tu proveedor de identidad corta su sesión MCP en el siguiente refresco de token.
Solo lectura por diseño — un guardián SQL del lado del servidor rechaza cualquier cosa que no sea SELECT, PRAGMA, EXPLAIN o WITH antes de que llegue al DO. Todas las declaraciones de escritura se bloquean a nivel del servidor MCP.
Sin acceso público a DO — la llamada RPC query() utiliza service bindings de Cloudflare (script_name), que permanecen completamente dentro de la red interna de Cloudflare. No hay un endpoint HTTP público hacia los DOs. El servidor MCP es la única vía de acceso.
Alcance explícito de namespaces — solo las clases de DO con bindings en wrangler.jsonc son descubribles y consultables. Nada se expone por defecto.

🛠️ Herramientas

Herramienta	Qué hace
`list_classes`	Lista las clases de DO consultables configuradas en tu implementación
`describe_schema`	Devuelve tablas y columnas para una instancia de DO
`execute_read_query`	Ejecuta SQL de solo lectura contra una instancia de DO

🚀 Configuración

1. Agrega un método `query()` a tus clases de DO

Cada clase de DO que quieras consultar necesita este método:

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

El guardián SQL del servidor MCP bloquea todas las declaraciones que no sean SELECT antes de que lleguen al DO.

2. Clona y configura

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

Edita wrangler.jsonc — agrega bindings de DO que apunten a tu Worker:

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

Cualquier binding de DO (excepto DO_MCP_AGENT) es automáticamente consultable — no se necesita configuración adicional.

3. Configura la autenticación (Cloudflare Access)

Sigue la guía Protege servidores MCP con Access para SaaS:

Crea una aplicación SaaS en Cloudflare One → Access → Applications
Selecciona OIDC como protocolo de autenticación
Establece la URL de redirección a https://your-worker.workers.dev/callback
En Policies, agrega una política de Access que controle quién puede conectarse (por ejemplo, lista de correos, grupo de IdP)
En Login methods, selecciona qué proveedores de identidad están disponibles (GitHub, Google, PIN de un solo uso, etc.)
Copia el Client ID y el Client Secret de la configuración de la aplicación

Luego establece los secretos:

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. Implementa

wrangler deploy

5. Conecta tu cliente MCP

En la primera conexión, te autenticarás mediante Cloudflare Access (ventana emergente del navegador). Después de eso, la sesión 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"

Luego ejecuta codex mcp login do-explorer para autenticarte.

OpenCode (opencode.json):

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

📋 Requisitos

5 minutos
Plan de pago de Cloudflare Workers
Durable Objects respaldados por SQLite (fecha de compatibilidad 2024-04-03+)
Cloudflare Zero Trust (para autenticación)

📄 Licencia

MIT

durable-objects-mcp

Documentación