bws-mcp

MCP remoto para Bitwarden Secrets Manager, que se ejecuta como un Cloudflare Worker.

Herramientas: bws_list_secrets, bws_get_secret, bws_put_secret (crear o actualizar) y bws_delete_secret. Cada herramienta requiere project. El Worker nunca busca entre proyectos. Los nombres de proyecto permitidos provienen de la variable de Worker BWS_ALLOWED_PROJECTS (lista separada por comas). La documentación y las pruebas usan prod y staging.

La autenticación es OAuth 2.1 con registro abierto de clientes dinámicos (Dynamic Client Registration) en /register. Tras el inicio de sesión con Cloudflare Access, el Worker completa la concesión MCP sin una segunda pantalla de consentimiento. Si la solicitud ya incluye un JWT de Cloudflare Access (Cf-Access-Jwt-Assertion), el Worker lo verifica por sí mismo y se salta el flujo OAuth de MCP.

ACCESS_SKIP existe solo para wrangler dev local. Solo se tiene en cuenta cuando el hostname de la solicitud es localhost o 127.0.0.1. No lo configures en producción.

El formulario Deploy to Cloudflare pide un secreto: BWS_ACCESS_TOKEN, el token de máquina de Bitwarden Secrets Manager. BWS_ALLOWED_PROJECTS ya está como prod,staging. El material HMAC de la cookie se crea en el primer uso de OAuth y se almacena en OAUTH_KV. El dominio del equipo, la audiencia, el client id, el client secret, la clave de cookie y la lista de correos permitidos no son campos del momento del despliegue.

En ese formulario:

• Deja el Comando de compilación vacío. Este Worker no tiene paso de compilación. Cloudflare deja la casilla en blanco porque package.json no tiene un script build. No añadas uno ficticio.

• Desmarca Compilaciones para ramas no productivas. La producción es solo main. preview_urls: false en wrangler.jsonc desactiva las URL de vista previa del Worker. No controla esta casilla. Cloudflare activa la casilla. No hay ninguna consulta de wrangler ni del botón que la desactive por defecto. Desmárcala aquí. Tras el despliegue también puedes desactivarla en Ajustes, Compilación, Control de ramas.

• El consentimiento OAuth de Cloudflare puede mostrar los ámbitos de Email Routing (email_routing). Esa lista son los ámbitos de inicio de sesión predeterminados de Wrangler, no un requisito de bws-mcp. Este Worker no tiene campo addresses ni bindings de correo. Conceder esos ámbitos no activa Email Routing. Rechazar todo el consentimiento bloquea el despliegue.

Despliegue

Botón. Pega BWS_ACCESS_TOKEN. Deja el comando de compilación vacío. Desmarca las compilaciones de ramas no productivas. KV se aprovisiona por ti. Access llega después de que el Worker esté en marcha.

CLI. Crea un namespace de KV, pon su id en OAUTH_KV en wrangler.jsonc, configura BWS_ACCESS_TOKEN (wrangler secret put o .dev.vars localmente) y luego ejecuta npx wrangler deploy.

Cloudflare Access (segundo paso)

El Worker se despliega sin Access. /authorize devuelve 503 hasta que completes esto.

JWTs de máquina en Cf-Access-Jwt-Assertion:

• ACCESS_TEAM_DOMAIN

• ACCESS_AUD

Access para SaaS OIDC (OAuth de MCP después de que un humano inicie sesión):

• CF_ACCESS_TEAM_DOMAIN

• CF_ACCESS_AUD

• CF_ACCESS_CLIENT_ID

• ALLOWED_EMAILS

• secret CF_ACCESS_CLIENT_SECRET

Configúralos en el panel o con wrangler después del primer despliegue. COOKIE_ENCRYPTION_KEY es opcional. Si lo omites, el Worker escribe una clave aleatoria en OAUTH_KV y la reutiliza.

El emisor de id_token de Access para SaaS es https://<team>.cloudflareaccess.com/cdn-cgi/access/sso/oidc/<client_id>, no la raíz del dominio del equipo.

Related MCP server: Identity Admin MCP Server

Seguridad

Este Worker lista, obtiene, crea, actualiza y elimina secretos en todos los proyectos de su lista permitida. Un cliente OAuth que complete /authorize para un humano aprobado puede rotar y eliminar esos secretos. Trátalo como acceso de reescritura de la bóveda, no como acceso de solo mirar.

Dos muros. No los combines en un solo secreto.

• El token de acceso de BWS es una cuenta de máquina, no un usuario. Su ACL de SM es solo qué proyectos puede tocar esa máquina.

• Los humanos aprobados pertenecen únicamente a la lista de correos permitidos del Worker (ALLOWED_EMAILS). No guardes una segunda lista de personas junto al token en Secrets Manager. SM no es una lista de personas.

• Token = ACL de proyectos de la máquina. Humanos = ALLOWED_EMAILS. No un solo secreto que haga ambas cosas.

Concede a la cuenta de máquina permiso de escritura (y eliminación) solo en los proyectos que este MCP deba tocar. En SM, un proyecto es la carpeta. El Worker no puede imponer una ACL más fina que ese token. Si el token puede escribir en un proyecto, bws_put_secret y bws_delete_secret pueden cambiar cualquier secreto dentro de él. Omite el permiso de escritura en el token solo si pretendes que este despliegue falle las escrituras.

BWS_ALLOWED_PROJECTS es una puerta de nombres de proyecto del Worker, no una lista de personas. Sigue usándola. Pon solo esos mismos proyectos en el token. Un nombre de más en el token y un nombre que falta en la variable, o al revés, es como te filtras o te quedas fuera.

ACCESS_SKIP es para wrangler dev local en localhost o 127.0.0.1. Nunca lo configures en producción. El botón Deploy to Cloudflare no lo inyecta, y debería seguir así.

El registro en /register es abierto, y /authorize da consentimiento automático tras el inicio de sesión con Access. Una persona en la lista permitida que haga clic en un enlace hostil de /authorize concede a ese cliente crear, rotar y eliminar en todos los proyectos permitidos.

Los bots que emiten tokens o credenciales deberían vivir en su propio proyecto de SM. Da a este Worker un token que pueda leer y escribir solo en ese proyecto para que un cliente de chat no pueda extraer ni reescribir el resto de la bóveda.

Crea un namespace de KV para este Worker y enlázalo como OAUTH_KV. No reutilices el KV de otro Worker. Las concesiones y los clientes DCR compartirían un almacén con cualquier otra cosa que viva allí.

Versiones y marketplaces

package.json version es la fuente de verdad. Estos deben coincidir con ella:

• Cursor .cursor-plugin/plugin.json

• Claude .claude-plugin/plugin.json

• Codex .codex-plugin/plugin.json

• Claude .claude-plugin/marketplace.json (la version de nivel superior y la version de la entrada del plugin)

• src/server.ts MCP version en new McpServer({ name: "bws-mcp", version: "..." })

Los marketplaces viven aquí:

• Cursor: .cursor-plugin

• Claude: .claude-plugin

• Codex: .codex-plugin, además del marketplace del repositorio en .agents/plugins

npm run ci ejecuta scripts/check-manifests.mjs. Eso hace fallar el PR si alguna de las versiones anteriores se desvía, o si la forma del esquema de un plugin o marketplace oficial es incorrecta. El nombre, la homepage y la licencia en los manifiestos de los plugins también deben coincidir con package.json.

Plugins

Cursor. Instala el plugin desde este repositorio y luego configura Worker URL con tu origen desplegado (sin ruta). MCP es ${WORKER_URL}/mcp.

Claude Code. Añade el marketplace de este repositorio (.claude-plugin/marketplace.json), instala bws-mcp y luego configura Worker URL de la misma manera.

Codex / ChatGPT Work. Ejecuta codex plugin marketplace add bchoor/bws-mcp y luego instala bws-mcp. Apunta .mcp.json a la URL /mcp de tu Worker después del despliegue. Codex no documenta un campo de configuración de Worker URL.

Otros clientes

Conectores de Claude. Aún puedes pegar https://<your-worker>/mcp en Claude Desktop o claude.ai. DCR registra el cliente en /register.

MCP personalizado de ChatGPT. Habilita el MCP personalizado en los ajustes de desarrollador, pega la misma URL /mcp y completa la redirección de OAuth.

Windsurf. Añade un servidor en mcp_config.json:

{
  "mcpServers": {
    "bws-mcp": {
      "serverUrl": "https://<your-worker>/mcp"
    }
  }
}

Cline. La misma forma en los ajustes de MCP de Cline, con url apuntando a /mcp.

El salto local (ACCESS_SKIP=1 en .dev.vars, nunca en git) solo funciona con http://localhost:8787 o 127.0.0.1.

Desarrollo

npm install
cp .dev.vars.example .dev.vars
# Fill BWS_ACCESS_TOKEN. Access vars and CF_ACCESS_CLIENT_SECRET are optional until you test OIDC.
npm run ci
npx wrangler dev

No abras un PR hasta que npm run ci esté en verde.