BeefChicken MCP

BeefChicken MCP 🚀

---

💡 O que é isso?

BeefChicken MCP é um servidor MCP genérico (proxy) que permite chamar qualquer Web API diretamente de clientes MCP, como Claude ou Cursor, bastando apenas colocar um openapi.yaml qualquer.

Nenhum código de implementação dependente de API específica é necessário. Como também é incluído um servidor OAuth 2.1 simplificado para clientes que não conseguem especificar diretamente uma chave de API, você pode conectar diretamente até mesmo ao Claude.ai (versão 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 que escolher o BeefChicken MCP?

❌ Problemas convencionais

• Para criar um servidor MCP, é preciso escrever bastante código em TypeScript ou Python para definir ferramentas e handlers de requisição.
• É trabalhoso corrigir, testar e reimplantar o código a cada mudança na especificação da API.
• Você quer usar suas próprias ferramentas no Claude.ai (versão Web), mas a barreira para construir um servidor de autenticação OAuth 2.1 é alta.

✅ Com o BeefChicken MCP

• 🧩 Zero linhas de código: basta substituir o docs/openapi.yaml pela especificação da API que você quer conectar!
• 🔐 Compatibilidade imediata com Claude.ai (versão Web): com o servidor OAuth 2.1 simplificado integrado, os conectores personalizados do Claude Web também conectam de primeira.
• ⚡️ Custo de manutenção do servidor: R$ 0: faça o deploy no Cloudflare Workers em poucos segundos (também compatível com Docker / Node.js). Dentro do plano gratuito, o servidor MCP é seu de graça.
• 📦 Ultra leve e com zero overhead de parsing: a especificação OpenAPI é convertida em JSON estático no momento do build (Workers), na inicialização (Docker) ou antes do deploy via npm run generate (Node.js). Nenhum parsing de YAML é necessário durante o processamento de requisições.

---

📊 Comparação com outras abordagens

Recurso / Característica	Implementação manual (SDK TS/Python)	Frameworks MCP comuns (FastMCP etc.)	BeefChicken MCP
Escrita de código	Necessária (muita)	Necessária (pouca)	Desnecessária (0 linhas — basta colocar o YAML)
Suporte a OpenAPI	❌ Requer conversão manual	⚠️ Requer implementação de handlers	✅ Apenas substituir o arquivo
Servidor OAuth 2.1 integrado	❌ Precisa criar do zero	❌ Precisa criar do zero	✅ Integrado (compatível imediato com Claude Web)
Cloudflare Workers	⚠️ Requer ajustes	⚠️ Requer ajustes	✅ Totalmente compatível (deploy com um clique)
Pegada em tempo de execução	-	Média a grande	Mínima (JSON estático)

---

✨ Principais recursos

• 🧩 Tudo se resolve trocando o arquivo de configuração: transforme qualquer Web API em ferramentas MCP sem escrever uma única linha de código.
• 🎯 Design dedicado exclusivamente ao proxy: elimina a necessidade de escrever handlers complexos e opera como um proxy puro, fiel à especificação.
• 📦 Conversão para JSON estático: sem parser YAML em tempo de execução nem lógica de resolução de $ref, minimizando o tamanho do bundle do Worker.
• 🔌 Retransmissão nativa de fetch: retransmite as respostas diretamente, sem interpor bibliotecas HTTP desnecessárias.
• 🛡️ Stateless e robusto: arquitetura de responseMode: 'json' que não depende de conexões SSE de longa duração. Design resistente a limites de timeout.

⚠️ Atenção antes de publicar em produção: Este servidor não possui limite de taxa próprio. Ao publicar, controle isso com as Rate Limiting Rules do Cloudflare ou por meio de um proxy reverso. Além disso, o servidor OAuth 2.1 incluído é uma implementação simplificada. Consulte a documentação de autenticação para mais detalhes.

---

🚀 Início rápido

1. Colocação da especificação

Substitua o docs/openapi.yaml pela especificação OpenAPI 3.0 da API que você quer conectar.

💡 Dica: OpenAPIs padrão como as do Stripe ou GitHub podem ser obtidas oficialmente ou em sites como o APIs.guru.

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

2. Deploy / execução

Para Cloudflare Workers:

npx wrangler deploy

Ao obter sucesso, o https://beefchicken-mcp.<あなたのサブドメイン>.workers.dev/mcp é emitido (para detalhes sobre configuração do D1 etc., consulte o procedimento de deploy).

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

A imagem é distribuída pelo GHCR — não é necessário fazer build. Se você montar o seu próprio openapi.yaml, ele será analisado na inicialização do contêiner para gerar o tools.json (se não montar, a especificação de exemplo incluída será usada). As tags disponíveis são: latest (último release), vX.Y.Z (versão específica fixa) e edge (build mais recente do branch main). Se quiser testar alterações locais, você pode fazer o build como antes com docker build -t beefchicken-mcp ..

3. Conexão a partir do cliente

Configure o cliente MCP com o cabeçalho Authorization: Bearer <対象APIのAPIキー> na URL emitida.

4. Uso direto de um cliente MCP local (Claude Desktop etc.)

Para clientes que iniciam o servidor MCP como subprocesso, como Claude Desktop / Claude Code, você pode conectar diretamente via npx sem precisar fazer deploy. Adicione o seguinte ao arquivo de configuração (ex.: 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"
      }
    }
  }
}

• Se você especificar o caminho absoluto para a especificação OpenAPI da API de destino em --openapi, as definições de ferramentas serão geradas em memória a cada inicialização (não é necessário npm run generate prévio). O mesmo comportamento ocorre com o argumento posicional sem a flag (["beefchicken-mcp", "/絶対パス/to/your-api-openapi.yaml"]). Se nenhum caminho for especificado, haverá fallback para o src/generated/tools.json pré-gerado dentro do repositório clonado (se não existir, a inicialização para com erro). Não há especificação padrão relativa ao cwd de propósito — como o cwd usado pelo cliente MCP ao iniciar o subprocesso é imprevisível, use sempre caminhos absolutos.
• O API_KEY é obrigatório. No modo stdio, o valor de API_KEY é usado diretamente como Authorization: Bearer para a API de destino, sem passar pelo servidor OAuth simplificado voltado à versão Web.
• Se quiser registrar o repositório clonado no cliente, defina command como npx, args como ["tsx", "src/stdio.ts", "--openapi", "./docs/openapi.yaml"] e configure o cwd (se o cliente suportar) para a raiz do repositório — o mesmo ponto de entrada (src/stdio.ts) será iniciado. Não use npm run stdio na configuração do cliente, pois a saída do banner do npm se mistura à saída padrão e corrompe a comunicação JSON-RPC do stdio. Use-o apenas para verificar o funcionamento isolado no seu terminal.

---

📚 Documentação

Tópico	Conteúdo
🔑 Autenticação	Método de envio da chave de API, diretrizes de design e como conectar conectores personalizados do claude.ai Web
☁️ Deploy	Procedimentos de deploy no Cloudflare Workers / Node.js / Docker
⚙️ Variáveis de ambiente	Referência de todos os itens de configuração
🛠 Desenvolvimento	Execução local, procedimentos de teste, atualização do OpenAPI e verificações de segurança

---

📜 Licença

MIT License. Consulte LICENSE para mais detalhes.