Obsidian + Claude a través de Cloudflare

Accede a tu Obsidian vault desde Claude (web, escritorio, Code) usando un servidor MCP en Cloudflare Workers + Containers.

Sin NAS, sin Docker Compose, sin túneles. Solo infraestructura de Cloudflare con el Agents SDK para un servidor MCP adecuado.

Arquitectura

Obsidian (phone, desktop)
        │
        │ Obsidian Sync (your existing subscription)
        ▼
Cloudflare Container (Node.js 22)
   runs `ob sync --continuous`
   serves vault files over HTTP API
        ▲
        │ container fetch (native)
        │
Cloudflare Worker (MCP server via Agents SDK)
   tools: list, read, search, write, append, delete
   auth via bearer token (or OAuth / Cloudflare Access)
        ▲
        │ MCP over Streamable HTTP
        │
Claude (web, desktop, Code)

El contenedor es la única fuente de verdad. Ejecuta obsidian-headless para sincronizar con Obsidian Sync y expone una API HTTP para operaciones de archivos. El Worker actúa como proxy de todas las llamadas a herramientas MCP hacia la API del contenedor.

Related MCP server: obsidianMCP

Herramientas MCP

Requisitos previos

• Cuenta de Cloudflare con plan Workers Paid ($5/mes)

• Suscripción activa a Obsidian Sync

• Node.js 22+ en tu estación de trabajo

• CLI de wrangler: npm install -g wrangler

Configuración

0. Inicio de sesión en Wrangler

wrangler login

Todos los alcances requeridos se conceden por defecto.

1. Generar token de autenticación de Obsidian

Un paso único en tu estación de trabajo:

npm install -g obsidian-headless

ob login
# Enter email, password, MFA code if enabled

ob sync-list-remote
# Note your vault name

2. Configurar el entorno

Copia el archivo de ejemplo de entorno y rellena tus valores:

cp .dev.vars.example .dev.vars

Edita .dev.vars con tus credenciales de Obsidian y el token de autenticación MCP opcional. Este archivo es utilizado por wrangler dev para el desarrollo local y por el script de configuración para enviar secretos a Cloudflare. Ya está en .gitignore.

3. Despliegue

Ejecuta el script de configuración para enviar todos los secretos y desplegar:

./scripts/setup.sh

O ejecuta los pasos individualmente:

./scripts/setup.sh secrets         # Push secrets to Cloudflare
./scripts/setup.sh validate        # Check prerequisites
./scripts/setup.sh deploy          # Validate + install deps + deploy + restart container
./scripts/setup.sh status          # Check sync container health
./scripts/setup.sh restart         # Restart sync container
./scripts/setup.sh container-logs  # View sync container logs

Tu servidor MCP está activo en: https://obsidian-mcp.<tu-subdominio>.workers.dev/mcp

4. Conectar Claude

Claude.ai (web)

Configuración → Conectores → Añadir conector personalizado:

• URL: https://obsidian-mcp.<tu-subdominio>.workers.dev/mcp?token=TU_TOKEN_AUTH_MCP

• Deja los campos OAuth en blanco — el token en la URL gestiona la autenticación

Claude Code

claude mcp add \
  --transport http \
  --scope user \
  obsidian-vault \
  https://obsidian-mcp.<your-subdomain>.workers.dev/mcp

Claude Desktop

Añade a claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-vault": {
      "url": "https://obsidian-mcp.<your-subdomain>.workers.dev/mcp"
    }
  }
}

Cómo fluyen los datos

Editas una nota en tu teléfono:

1. Obsidian Sync envía el cambio

2. ob sync --continuous del contenedor lo descarga a /vault

3. La próxima vez que Claude lea o busque, el Worker redirige la solicitud a la API HTTP del contenedor, que lee directamente desde /vault

Claude crea una nota:

1. El Worker recibe la llamada MCP write_note

2. El Worker la redirige a la API HTTP del contenedor

3. El contenedor escribe el archivo en /vault

4. ob sync detecta el nuevo archivo y lo envía a través de Obsidian Sync

5. Aparece en tu teléfono y escritorio

Desarrollo

# Local dev (MCP server only, no container)
npm run dev

# Deploy
npm run deploy

Coste

Estructura del proyecto

obsidian-mcp/
├── src/
│   └── index.ts              # MCP server (Agents SDK, proxies to container)
├── sync-container/
│   ├── Dockerfile            # Headless sync container image
│   ├── entrypoint.sh         # Auth, sync startup
│   └── server.js             # HTTP API for vault file operations
├── scripts/
│   └── setup.sh              # Push secrets, deploy
├── .dev.vars.example         # Template for env vars / secrets
├── wrangler.jsonc            # Worker + Container config
└── package.json

Próximos pasos

Estos se dejan como ejercicios para fortalecer la configuración según tus necesidades:

Refuerzo de autenticación

La autenticación incluida (secreto MCP_AUTH_TOKEN) admite tanto cabeceras Authorization: Bearer como parámetros de consulta ?token=. El enfoque de token en la URL es conveniente para conectores de Claude.ai donde las cabeceras personalizadas no siempre están disponibles.

Para despliegues compartidos o públicos, considera opciones más fuertes:

• Cloudflare Access: Pon Zero Trust Access delante del Worker para SSO basado en identidad con registros de auditoría y sin cambios de código

• OAuth: Integra workers-oauth-provider para flujos OAuth de GitHub/Google

Autenticación del contenedor

Comprueba si obsidian-headless admite autenticación basada en --token o variables de entorno para ob login para evitar avisos interactivos. Si no, persiste la sesión de autenticación desde un inicio de sesión interactivo único y restáurala al iniciar el contenedor.

Resiliencia ante reinicios del contenedor

El archivo de estado sqlite de ob vive en el disco efímero del contenedor. Un reinicio activa una resincronización completa. Para solucionarlo: añade un trap SIGTERM en entrypoint.sh que persista el archivo de estado, y restáuralo al iniciar.

Rendimiento de búsqueda

La búsqueda de fuerza bruta lee cada archivo .md por consulta — bien para <500 archivos. Para vaults más grandes, construye un índice de búsqueda en D1 o Workers KV.

Adjuntos

Actualmente filtra solo a .md. Amplía para admitir imágenes, PDFs y otros adjuntos del vault con herramientas adicionales.

Solución de problemas

Docker debe estar ejecutándose — El contenedor de sincronización requiere Docker. Ejecuta docker info para verificar. El subcomando validate comprueba esto automáticamente.

Dos contraseñas — OBSIDIAN_PASSWORD es tu contraseña de cuenta de Obsidian (usada para iniciar sesión en obsidian.md). VAULT_PASSWORD es la contraseña separada de cifrado de extremo a extremo establecida en Obsidian → Sync → Cifrado. Deja VAULT_PASSWORD vacío si tu vault no usa E2EE.

El despliegue no reinicia los contenedores — wrangler deploy no reinicia los contenedores en ejecución. El script de configuración gestiona esto automáticamente. Si despliegas manualmente, reinicia con ./scripts/setup.sh restart.

Los registros del contenedor no están en wrangler tail — La salida estándar del contenedor no se transmite a través de wrangler tail. Usa ./scripts/setup.sh container-logs en su lugar.

Referencia de componentes