BeefChicken MCP

BeefChicken MCP 🚀

---

💡 ¿Qué es esto?

BeefChicken MCP es un servidor MCP genérico (proxy) que, con solo colocar un openapi.yaml, permite que cualquier API web sea llamada directamente desde clientes MCP como Claude o Cursor.

No se necesita ningún código de implementación dependiente de una API específica. Incluye incluso un servidor OAuth 2.1 simplificado para clientes que no pueden especificar claves API directamente, por lo que también puedes conectarlo tal cual a Claude.ai (versión web).

graph LR
    subgraph Client [AIクライアント]
        Claude[🤖 Claude.ai / Cursor 等]
    end

    subgraph Proxy [BeefChicken MCP]
        MCP[⚡ MCPサーバー<br/>Workers / Node.js / Docker]
        OAuth[🔐 内蔵 OAuth 2.1]
    end

    subgraph Target [接続先API]
        Spec[📄 docs/openapi.yaml]
        API[🌐 対象Web API<br/>Stripe / GitHub / 社内API]
    end

    Spec -->|ビルド時/起動時に静的JSON化| MCP
    Claude -->|MCPプロトコル / OAuth| MCP
    MCP -->|ネイティブfetch| API

---

⚡ ¿Por qué BeefChicken MCP?

❌ Problemas tradicionales

• Para crear un servidor MCP, es necesario escribir definiciones de herramientas y manejadores de solicitudes en TypeScript o Python.
• Cada vez que cambia la especificación de la API, es tedioso corregir, probar y volver a implementar el código.
• Quieres usar tus propias herramientas en Claude.ai (versión web), pero la barrera para construir un servidor de autenticación OAuth 2.1 es alta.

✅ Con BeefChicken MCP

• 🧩 0 líneas de código: ¡Solo reemplaza docs/openapi.yaml con la especificación de la API que quieras conectar!
• 🔐 Compatible al instante con Claude.ai (versión web): Con el servidor OAuth 2.1 simplificado integrado, los conectores personalizados de Claude web se conectan de un solo golpe.
• ⚡️ Costo de mantenimiento del servidor: 0 yenes: Despliega en Cloudflare Workers en segundos (también compatible con Docker / Node.js). Dentro del plan gratuito, el servidor MCP es tuyo sin costo.
• 📥 La ruta más corta sin necesidad de implementación: Para clientes locales como Claude Desktop, no se necesita clonar ni compilar. Inicia al instante desde npm con npx beefchicken-mcp.
• 📦 Ultraligero y sin sobrecarga de análisis: La especificación OpenAPI se convierte a JSON estático en el momento de la compilación (Workers), al inicio (Docker) o antes de la implementación con npm run generate (Node.js). No se realiza ningún análisis YAML durante el procesamiento de solicitudes.

---

📊 Comparación con otros métodos

Función / Característica	Implementación manual (SDK TS/Python)	Frameworks MCP generales (FastMCP, etc.)	BeefChicken MCP
Escritura de código	Necesaria (mucha)	Necesaria (poca)	No necesaria (0 líneas, solo colocar YAML)
Compatibilidad con OpenAPI	❌ Requiere conversión manual	⚠️ Requiere implementación de manejadores	✅ Solo reemplazar el archivo
Servidor OAuth 2.1 integrado	❌ Debe crearse manualmente	❌ Debe crearse manualmente	✅ Integrado (compatible al instante con Claude Web)
Cloudflare Workers	⚠️ Requiere ajustes	⚠️ Requiere ajustes	✅ Totalmente compatible (implementación con un botón)
Huella en tiempo de ejecución	-	Media a grande	Mínima (JSON estático)

---

✨ Características principales

• 🧩 Solo reemplazar el archivo de configuración: Convierte cualquier API web en herramientas MCP sin escribir ni una línea de código.
• 🎯 Diseño enfocado en ser un proxy dedicado: Elimina la escritura de manejadores complejos y opera como un proxy puro según la especificación.
• 📦 Conversión a JSON estático: No incluye analizador YAML ni lógica de resolución de $ref en tiempo de ejecución, minimizando el tamaño del bundle del Worker.
• 🔌 Retransmisión nativa de fetch: Retransmite las respuestas directamente sin intermediar bibliotecas HTTP innecesarias.
• 🛡️ Sin estado y robusto: Configuración de responseMode: 'json' que no depende de la retención prolongada de SSE. Diseño robusto y resistente a límites de tiempo de espera.
• 📦 4 formas de distribución: Cloudflare Workers / Node.js / imagen Docker (GHCR) / CLI npm (npx beefchicken-mcp). Puedes elegir según tu caso de uso.

⚠️ Nota antes de la publicación en producción: Este servidor no tiene límite de tasa por sí mismo. Al publicarlo, controla con Rate Limiting Rules de Cloudflare o un proxy inverso. Además, el servidor OAuth 2.1 incluido es una implementación simplificada. Consulta la documentación de autenticación para más detalles.

---

🚀 Inicio rápido

1. Colocación de la especificación

Reemplaza docs/openapi.yaml con la especificación OpenAPI 3.0 de la API que quieras conectar.

💡 Consejo: Los OpenAPI estándar de Stripe, GitHub, etc., se pueden obtener de fuentes oficiales o de APIs.guru.

npm install
npm run generate   # docs/openapi.yaml を解析し、src/generated/tools.json を自動生成

2. Implementación / Ejecución

Para clientes MCP locales (Claude Desktop, etc.) — la ruta más corta:

npx beefchicken-mcp --openapi /絶対パス/to/openapi.yaml

Se distribuye como paquete npm, por lo que no necesitas clonar ni implementar (en esta ruta, tampoco necesitas npm install / npm run generate del paso 1; la especificación indicada se analiza en memoria en cada inicio). Consulta el paso 4 para conocer el método concreto de registro en la configuración del cliente.

Para Cloudflare Workers:

npx wrangler deploy

Si tiene éxito, se emite https://beefchicken-mcp.<あなたのサブドメイン>.workers.dev/mcp (consulta procedimiento de implementación para detalles como la configuración de D1).

Para Node.js:

API_BASE_URL=https://api.example.com npm run node:dev

Para Docker:

docker run -p 3000:3000 \
  -e HOST=0.0.0.0 \
  -e ALLOWED_HOSTS=127.0.0.1,localhost \
  -e API_BASE_URL=https://api.example.com \
  -v $(pwd)/docs/openapi.yaml:/app/docs/openapi.yaml:ro \
  ghcr.io/watanabebashi/beefchicken-mcp

La imagen se distribuye desde GHCR y no requiere compilación. Si montas tu propio openapi.yaml, se analiza al iniciar el contenedor y se genera tools.json (si no se monta, se usa la especificación de muestra incluida). Las etiquetas disponibles son latest (última versión), vX.Y.Z (versión específica fija) y edge (última compilación de la rama main). Si quieres probar cambios locales, puedes compilar como siempre con docker build -t beefchicken-mcp ..

3. Conexión desde el cliente

Configura el encabezado Authorization: Bearer <対象APIのAPIキー> en la URL emitida y regístrala en el cliente MCP.

4. Uso directo desde clientes MCP locales (Claude Desktop, etc.)

Para clientes que inician el servidor MCP como subproceso, como Claude Desktop / Claude Code, puedes conectarte directamente a través de npx sin necesidad de implementación. Agrega lo siguiente al archivo de configuración (ejemplo: claude_desktop_config.json).

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["beefchicken-mcp", "--openapi", "/絶対パス/to/your-api-openapi.yaml"],
      "env": {
        "API_KEY": "<対象APIのAPIキー>",
        "API_BASE_URL": "https://api.example.com"
      }
    }
  }
}

• Si especificas la ruta absoluta a la especificación OpenAPI de la API de destino en --openapi, se generan las definiciones de herramientas en memoria en cada inicio (no se necesita npm run generate previamente). El mismo comportamiento se obtiene con un argumento posicional sin la bandera (["beefchicken-mcp", "/絶対パス/to/your-api-openapi.yaml"]). Si no se especifica ninguna ruta, se recurre a src/generated/tools.json previamente generado dentro del repositorio clonado (si no existe, se detiene con un error al inicio). Deliberadamente no se incluye una especificación predeterminada relativa a cwd. Dado que el cwd al iniciar el subproceso desde el cliente MCP es impredecible, especifica siempre una ruta absoluta.
• API_KEY es obligatorio. El modo stdio no pasa por el servidor OAuth simplificado para la versión web; usa el valor de API_KEY directamente como Authorization: Bearer para la API de destino.
• Si quieres registrar el repositorio clonado en el cliente, establece command como npx, args como ["tsx", "src/stdio.ts", "--openapi", "./docs/openapi.yaml"], y cwd (si el cliente lo admite) en la raíz del repositorio; se iniciará el mismo punto de entrada (src/stdio.ts) (no uses npm run stdio para la configuración del cliente, ya que la salida del banner de npm se mezcla con la salida estándar y rompe la comunicación JSON-RPC de stdio. Úsalo solo para verificar el funcionamiento independiente en tu terminal local).

---

📚 Documentación

Tema	Contenido
🔑 Autenticación	Método de envío de claves API, política de diseño, método de conexión del conector personalizado para claude.ai versión web
☁️ Implementación	Procedimientos de implementación en Cloudflare Workers / Node.js / Docker
⚙️ Variables de entorno	Referencia de todos los elementos de configuración
🛠 Desarrollo	Ejecución local, procedimientos de prueba, actualización de OpenAPI, verificación de seguridad

---

📜 Licencia

Licencia MIT. Consulta LICENSE para más detalles.