Kintone OAuth MCP Server

Um servidor MCP de exemplo para kintone usando OAuth, implantável no Cloudflare Workers.

Documentação

Servidor remoto Model Context Protocol (MCP) para kintone via OAuth no Cloudflare Workers

Este é um código de exemplo de servidor Model Context Protocol (MCP) para kintone, implantável como Cloudflare Workers.

Não é necessário configurar o programa localmente; você pode usá-lo a partir do Claude ou ChatGPT na versão web.

Por meio da autenticação OAuth, a integração com o kintone é realizada com segurança, sem armazenar informações confidenciais, como chaves de API, localmente. Uma vez implantado, todos os usuários que utilizam o mesmo domínio cybozu.com podem compartilhar e usar o servidor.

🚀 Plataformas com suporte confirmado

Em 11 de setembro de 2025, no ChatGPT Web, parece que o recurso está disponível como versão beta para contas Pro ou Plus do ChatGPT, habilitando Configurações → Conectores → Configurações avançadas → Modo de desenvolvedor.

📋 Ambiente necessário

Conta Cloudflare
Privilégios de administrador no domínio cybozu.com (para criar o cliente OAuth)
Node.js 18 ou superior
Wrangler CLI

🔧 Procedimento de configuração

1. Criar um cliente OAuth na administração comum do cybozu.com

Adicione um cliente OAuth seguindo a documentação oficial da Cybozu.

Itens de configuração:

Nome do cliente: um nome fácil de entender (ex.: "kintone MCP Server")
Endpoint de redirecionamento: defina temporariamente como https://localhost:8788/callback
Escopos: selecione os seguintes
- k:app_record:read - leitura de registros
- k:app_record:write - gravação de registros
- k:app_settings:read - leitura das configurações do aplicativo
- k:app_settings:write - gravação das configurações do aplicativo
- k:file:read - leitura de arquivos
- k:file:write - gravação de arquivos

Anote o "Client ID" e o "Client Secret" exibidos após salvar.
Em "Configurações do usuário" do cliente OAuth, especifique os usuários que poderão usar este MCP Server.

2. Configuração do projeto

# リポジトリのクローン
git clone https://github.com/r3-yamauchi/kintone-oauth-mcp-server-cfw.git
cd kintone-oauth-mcp-server-cfw

# 依存関係のインストール
npm install

3. Configuração das variáveis de ambiente

Insira os valores anotados ao criar o cliente OAuth no arquivo de configuração do Wrangler ( wrangler.jsonc ):

"vars": {
   "CYBOZU_CLIENT_ID": "<your cybozu.com client id>",
   "CYBOZU_CLIENT_SECRET": "<your cybozu.com client secret>",
   "CYBOZU_SUBDOMAIN": "<your cybozu.com sub domain>", # your cybozu.com subdomain
   "COOKIE_ENCRYPTION_KEY": "<your cookie encryption key>", # add any random string here e.g. openssl rand -hex 32
   "WORKER_URL": "<your worker url>"
},

4. Criação do namespace KV

Execute o comando abaixo no wrangler CLI para criar o namespace KV:

wrangler kv:namespace create "OAUTH_KV"

No arquivo de configuração do Wrangler (wrangler.jsonc), insira o ID do KV criado no campo <your cloudflare kv id>.
Execute o comando abaixo para implantar no Cloudflare Workers.

wrangler deploy

Após a conclusão da implantação, defina a URL do Workers no campo "Endpoint de redirecionamento" do cliente OAuth na tela de administração comum do cybozu.com, adicionando /callback ao final. Você inserirá algo como https://<your-subdomain>.workers.dev/callback.

Acessar o servidor MCP remoto pelo aplicativo web Claude

Acesse a tela de gerenciamento de integrações do aplicativo web Claude e clique em "Adicionar integração".
Em "Nome da integração", use um nome fácil de entender, pois será usado para identificar o MCP Server.
Em "URL da integração", insira https://<your-subdomain>.workers.dev/sse.

Após clicar no botão "Adicionar", clique em "Integrar/Conectar". A tela de confirmação OAuth será exibida; clique em "Approve"/"Permitir".

O servidor MCP remoto estará disponível no aplicativo web Claude.

Acessar o servidor MCP remoto pelo Claude Desktop

No Claude Desktop, abra Settings -> Developer -> Edit Config e adicione a seguinte configuração. Após reiniciar o Claude Desktop, a tela de login OAuth será exibida; ao concluir o fluxo de autenticação, o Claude poderá acessar o servidor MCP.

{
  "mcpServers": {
    "kintone": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-subdomain>.workers.dev/sse"
      ]
    }
  }
}

Explicação

🎯 O que isto faz

É um servidor que permite que assistentes de IA (como o Claude) acessem a API do kintone com segurança.

Ele opera no Cloudflare Workers e realiza a integração com o kintone por meio de autenticação OAuth, sem armazenar credenciais localmente.

🔧 Principais recursos

1. Ferramentas disponíveis (28 ferramentas no total)

Operações de registros

getRecords - obtém a lista de registros
getRecord - obtém um único registro
addRecord - adiciona um registro
addRecords - adiciona vários registros de uma vez
updateRecord - atualiza um registro
getRecordComments - obtém os comentários de um registro
addRecordComment - publica um comentário em um registro
evaluateRecordsAcl - avalia os direitos de acesso de registros

Configurações do aplicativo

getApp - obtém as informações básicas do aplicativo
getAppFields - obtém a lista de campos
searchApps - pesquisa aplicativos
getAppSettings - obtém as configurações gerais do aplicativo
getFormLayout - obtém o layout do formulário
getViews - obtém as configurações de visualizações
getProcessManagement - obtém as configurações de gerenciamento de processos
getAppReports - obtém as configurações de gráficos
getAppCustomize - obtém as configurações de personalização JavaScript/CSS
getAppActions - obtém as configurações de ações

Operações de arquivos

uploadFile - envio de arquivo
downloadFile - download de arquivo

Direitos de acesso

getAppAcl - obtém os direitos de acesso do aplicativo
getRecordAcl - obtém as configurações de direitos de acesso de registros
getFieldAcl - obtém os direitos de acesso de campos

Configurações de notificação

getAppNotificationsGeneral - obtém notificações por condição do aplicativo
getAppNotificationsPerRecord - obtém notificações por condição de registros
getAppNotificationsReminder - obtém notificações de lembrete

Gerenciamento de implantação

updateAppCustomize - atualiza a personalização JavaScript/CSS
deployApp - reflete as configurações do aplicativo no ambiente de produção

2. Autenticação OAuth dupla

Autenticação com o cliente MCP (Claude)
Autenticação com a conta kintone/Cybozu

3. Fluxo de autenticação

O cliente MCP se conecta
O usuário aprova na tela de consentimento
Redirecionamento para a tela OAuth do kintone
Após a autenticação no kintone, o token de acesso é obtido
Uma conexão segura é estabelecida

🏗️ Arquitetura

Cloudflare Workers - serverless e escalável
KV Storage - persistência do estado OAuth
Cookie criptografado - memorização de clientes aprovados

💡 Vantagens

Seguro - não é necessário compartilhar chaves de API
Suporte a múltiplos usuários - vários usuários podem usar com uma única implantação
Compatível com navegador/desktop - utilizável a partir do Claude Web ou Claude Desktop
Custo-benefício - execução serverless apenas quando necessário

Este projeto é uma implementação completa de servidor MCP, baseada no template OAuth do GitHub e personalizada especificamente para o kintone.

Origem deste projeto

Este projeto foi originalmente criado usando o template OAuth do GitHub da Cloudflare:

npm create cloudflare@latest -- kintone-oauth-mcp-server-cfw --template=cloudflare/ai/demos/remote-mcp-github-oauth

Este template (descrito no guia de Remote MCP Server da Cloudflare) fornece a base para a construção de servidores MCP com autenticação OAuth. Neste projeto, o template foi adaptado para o OAuth da Cybozu/kintone, implementando um fluxo de autenticação compatível com a implementação OAuth 2.0 da Cybozu.

Principais alterações em relação ao template original

Para adaptar o template OAuth do GitHub ao kintone, foram feitas as seguintes alterações:

Handlers OAuth: criado src/cybozu-handler.ts para processar o fluxo OAuth do kintone (substituindo github-handler.ts)
Endpoints OAuth: alterados para os endpoints OAuth da Cybozu:
- Autorização: https://{subdomain}.cybozu.com/oauth2/authorization
- Token: https://{subdomain}.cybozu.com/oauth2/token
Método de autenticação: alinhado à especificação OAuth 2.0 do kintone (as credenciais são incluídas no corpo da requisição)
Variáveis de ambiente: alteradas de GitHub para kintone:
- GITHUB_CLIENT_ID → CYBOZU_CLIENT_ID
- GITHUB_CLIENT_SECRET → CYBOZU_CLIENT_SECRET
- Adicionado CYBOZU_SUBDOMAIN (para o subdomínio do kintone)
Escopos: uso dos escopos da API do kintone
- k:app_record:read - permissão de leitura de registros
- k:app_record:write - permissão de gravação de registros
- k:app_settings:read - permissão de leitura das configurações do aplicativo
- k:app_settings:write - permissão de gravação das configurações do aplicativo (para atualização de personalizações)
- k:file:read - permissão de leitura de arquivos
- k:file:write - permissão de gravação de arquivos

Desenvolvimento e testes locais

Inicie o servidor com HTTPS habilitado:

wrangler dev --local-protocol https

Conecte-se a https://localhost:8788/sse no Inspector para testar.

Atenção: no primeiro acesso, você precisará aceitar o aviso de certificado autoassinado no navegador.

Solução de problemas de configuração OAuth

Se ocorrer erro 401

Verifique os seguintes pontos:

Configuração no Cybozu Developer Network
- Confirme se o URI de redirecionamento corresponde exatamente
  - Produção: https://<your-subdomain>.workers.dev/callback
  - Desenvolvimento: https://localhost:8788/callback
- O aplicativo OAuth está "habilitado"
- client_id e client_secret foram copiados corretamente
- Os escopos necessários estão configurados: k:app_record:read k:app_record:write k:app_settings:read k:app_settings:write k:file:read k:file:write

Verificação das variáveis de ambiente

# .dev.varsファイルまたはwrangler secretsで以下を確認
CYBOZU_CLIENT_ID=<your-client-id>
CYBOZU_CLIENT_SECRET=<your-client-secret>
CYBOZU_SUBDOMAIN=<your-subdomain>
COOKIE_ENCRYPTION_KEY=<random-32-char-string>

Verificação dos logs No console ao iniciar o servidor de desenvolvimento, verifique:
- OAuth Callback Received - se o callback foi recebido corretamente
- Starting Token Exchange - se a troca de token foi iniciada
- O conteúdo detalhado das respostas de erro
Especificação OAuth do kintone
- Endpoint de autorização: https://{subdomain}.cybozu.com/oauth2/authorization
- Endpoint de token: https://{subdomain}.cybozu.com/oauth2/token
- Método de autenticação: incluir client_id e client_secret no corpo da requisição
- Formato da resposta: JSON
Modo de depuração Para ver logs detalhados, inicie o servidor de desenvolvimento e execute:
```
npm run dev
```

Visão geral do funcionamento

Provedor OAuth

A biblioteca OAuth Provider é uma implementação de servidor OAuth 2.1 para Cloudflare Workers. Essa biblioteca é responsável por todo o fluxo OAuth (emissão, validação e gerenciamento de tokens). Especificamente:

Autenticação do cliente MCP
Gerenciamento da conexão com o serviço OAuth do kintone
Armazenamento seguro de tokens e estado de autenticação no KV Storage

MCP Remote

A biblioteca MCP Remote permite que o servidor forneça ferramentas ao cliente:

Define o protocolo de comunicação entre cliente e servidor
Fornece a forma de definição de ferramentas
Gerencia a serialização/desserialização de requisições/respostas
Mantém a conexão Server-Sent Events (SSE) entre cliente e servidor

Riscos ao usar um MCP Server

Ao usar um MCP server criado e implementado por terceiros, lembre-se sempre de que existem riscos envolvidos.

kintone AI Lab e o estado atual dos MCP Servers para kintone

"kintone" é uma marca registrada da Cybozu, Inc.

O conteúdo aqui descrito tem finalidade informativa e não oferece suporte individual. Não é possível responder a perguntas sobre as configurações ou a problemas de funcionamento no seu ambiente; agradecemos a compreensão.