リモート Model Context Protocol (MCP) サーバー for kintone via OAuth on Cloudflare Workers

通过 Cloudflare Workers 上的 OAuth 连接 kintone 的远程 Model Context Protocol (MCP) 服务

这是一个适用于 kintone 的 Model Context Protocol (MCP) 服务示例代码，可部署为 Cloudflare Workers。

无需在本地设置程序，即可通过 Claude 或 ChatGPT 的网页版使用。

通过 OAuth 认证，无需在本地保存 API 密钥等机密信息，即可安全地连接 kintone。 部署一次后，所有使用同一 cybozu.com 域名的用户都可以共享使用。

🚀 已确认支持的平台

• Claude Web版
• Claude Desktop（macOS/Windows）
• Postman
• Cloudflare AI Playground
• ChatGPT Web版

截至 2025年9月11日，ChatGPT Web版似乎可以通过 ChatGPT Pro 或 Plus 账户，在设置 → 连接器 → 高级设置 → 开发者模式中启用后，作为 Beta 版使用。

📋 所需环境

• Cloudflare 账户
• cybozu.com 域名的管理员权限（用于创建 OAuth 客户端）
• Node.js 18 以上版本
• Wrangler CLI

🔧 设置步骤

1. 在 cybozu.com 统一管理中创建 OAuth 客户端

按照 Cybozu 官方文档添加 OAuth 客户端。

设置项目：

• 客户端名称：易于识别的名称（例如：「kintone MCP Server」）
• 重定向端点：暂时设置为 https://localhost:8788/callback
• 范围：选择以下项目
  • k:app_record:read - 读取记录
  • k:app_record:write - 写入记录
  • k:app_settings:read - 读取应用设置
  • k:app_settings:write - 写入应用设置
  • k:file:read - 读取文件
  • k:file:write - 写入文件

• 保存后，请记下显示的「客户端 ID」和「客户端密钥」。
• 在 OAuth 客户端的「用户设置」中，指定要使用此 MCP 服务的用户。

2. 设置项目

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

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

3. 设置环境变量

• 将创建 OAuth 客户端时记下的值填入 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. 创建 KV 命名空间

• 使用 wrangler CLI 执行以下命令，创建 KV 命名空间：

wrangler kv:namespace create "OAUTH_KV"

• 在 Wrangler 配置文件（wrangler.jsonc）中的 <your cloudflare kv id> 处填入创建的 KV ID。

• 执行以下命令，将其部署到 Cloudflare Workers。

wrangler deploy

• 部署完成后，将 Workers 的 URL 设置到 cybozu.com 统一管理界面中 OAuth 客户端的「重定向端点」栏，并在末尾添加 /callback。输入 https://<your-subdomain>.workers.dev/callback。

从 Claude Web 应用访问远程 MCP 服务

• 访问 Claude Web 应用的集成管理页面， 点击「添加集成」。

• 「集成名称」将作为识别 MCP 服务的名称，请设置一个易于识别的名称。

• 在「集成 URL」中输入 https://<your-subdomain>.workers.dev/sse。

• 点击「添加」按钮后，点击「连接/连接」。出现 OAuth 确认页面时，点击「Approve」「允许」。

• 现在可以从 Claude Web 应用使用远程 MCP 服务了。

从 Claude Desktop 访问远程 MCP 服务

在 Claude Desktop 中打开 Settings -> Developer -> Edit Config，并添加以下设置。重启 Claude Desktop 后会显示 OAuth 登录页面，完成认证流程后，Claude 即可访问 MCP 服务。

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

说明

🎯 这是做什么的

这是一个让 AI 助手（例如 Claude）能够安全访问 kintone API 的服务。

它运行在 Cloudflare Workers 上，无需在本地保存认证信息，即可通过 OAuth 认证连接 kintone。

🔧 主要功能

1. 利用可能なツール（全28ツール）

レコード操作

• getRecords - レコード一覧を取得
• getRecord - 単一レコードを取得
• addRecord - レコードを追加
• addRecords - 複数レコードを一括追加
• updateRecord - レコードを更新
• getRecordComments - レコードのコメントを取得
• addRecordComment - レコードにコメントを投稿
• evaluateRecordsAcl - レコードのアクセス権を評価

アプリ設定

• getApp - アプリ基本情報を取得
• getAppFields - フィールド一覧を取得
• searchApps - アプリを検索
• getAppSettings - アプリの一般設定を取得
• getFormLayout - フォームレイアウトを取得
• getViews - 一覧（ビュー）設定を取得
• getProcessManagement - プロセス管理設定を取得
• getAppReports - グラフ設定を取得
• getAppCustomize - JavaScript/CSSカスタマイズ設定を取得
• getAppActions - アクション設定を取得

ファイル操作

• uploadFile - ファイルアップロード
• downloadFile - ファイルダウンロード

アクセス権

• getAppAcl - アプリのアクセス権を取得
• getRecordAcl - レコードのアクセス権設定を取得
• getFieldAcl - フィールドのアクセス権を取得

通知設定

• getAppNotificationsGeneral - アプリの条件通知を取得
• getAppNotificationsPerRecord - レコードの条件通知を取得
• getAppNotificationsReminder - リマインダー通知を取得

デプロイ管理

• updateAppCustomize - JavaScript/CSSカスタマイズを更新
• deployApp - アプリ設定を運用環境へ反映

2. 二重OAuth認証

• MCPクライアント（Claude）との認証
• kintone/Cybozuアカウントとの認証

3. 認証フロー

1. MCPクライアントが接続
2. ユーザーが承認画面で許可
3. kintoneのOAuth画面へリダイレクト
4. kintoneでの認証完了後、アクセストークンを取得
5. 安全な接続が確立

🏗️ アーキテクチャ

• Cloudflare Workers - サーバーレスでスケーラブル
• KV Storage - OAuth状態の永続化
• 暗号化されたCookie - 承認済みクライアントの記憶

💡 メリット

1. セキュア - APIキーの共有不要
2. マルチユーザー対応 - 1つのデプロイで複数ユーザーが利用可能
3. ブラウザ/デスクトップ対応 - Claude WebやClaude Desktopから利用可能
4. コスト効率 - サーバーレスで必要な時だけ実行

このプロジェクトは、GitHubのOAuthテンプレートをベースに、kintone専用にカスタマイズされた本格的なMCPサーバー実装となっています。

このプロジェクトの由来

このプロジェクトは、もともとCloudflareのGitHub OAuthテンプレートを使用して作成されました：

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

このテンプレート（CloudflareのRemote MCP Serverガイドで説明あり）は、OAuth認証を備えたMCPサーバーの構築基盤を提供します。本プロジェクトでは、このテンプレートを Cybozu/kintone OAuth 用に改修し、CybozuのOAuth 2.0実装に対応した認証フローを実現しています。

元のテンプレートからの主な変更点

GitHub OAuthテンプレートをkintoneに対応させるため、以下の変更を行いました：

1. OAuthハンドラー: src/cybozu-handler.ts を新規作成し、kintoneのOAuthフローを処理（ github-handler.ts を置き換え）
2. OAuthエンドポイント: Cybozu OAuthのエンドポイントに変更：
   • 認可: https://{subdomain}.cybozu.com/oauth2/authorization
   • トークン: https://{subdomain}.cybozu.com/oauth2/token
3. 認証方式: kintoneのOAuth 2.0仕様に合わせ（クレデンシャルはリクエストボディに含める）
4. 環境変数: GitHub用からkintone用に変更：
   • GITHUB_CLIENT_ID → CYBOZU_CLIENT_ID
   • GITHUB_CLIENT_SECRET → CYBOZU_CLIENT_SECRET
   • CYBOZU_SUBDOMAIN を追加（kintoneのサブドメイン用）
5. スコープ: kintone APIのスコープを使用
   • k:app_record:read - レコード読み取り権限
   • k:app_record:write - レコード書き込み権限
   • k:app_settings:read - アプリ設定読み取り権限
   • k:app_settings:write - アプリ設定書き込み権限（カスタマイズ更新用）
   • k:file:read - ファイル読み取り権限
   • k:file:write - ファイル書き込み権限

ローカル開発とテスト

HTTPSを有効にしてサーバーを起動:

wrangler dev --local-protocol https

Inspectorで https://localhost:8788/sse に接続してテスト。

注意: 初回アクセス時には、ブラウザで自己署名証明書の警告を受け入れる必要があります。

OAuth設定トラブルシューティング

401エラーが発生する場合

以下の点を確認してください：

1. Cybozu Developer Networkでの設定

   • リダイレクトURIが完全一致していることを確認
     • 本番環境: https://<your-subdomain>.workers.dev/callback
     • 開発環境: https://localhost:8788/callback
   • OAuthアプリケーションが「有効」になっている
   • client_idとclient_secretが正しくコピーされている
   • 必要なスコープが設定されている: k:app_record:read k:app_record:write k:app_settings:read k:app_settings:write k:file:read k:file:write

2. 環境変数の確認

   # .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>
   

3. ログの確認 開発サーバー起動時のコンソールで以下を確認：

   • OAuth Callback Received - コールバックが正しく受信されているか
   • Starting Token Exchange - トークン交換が開始されているか
   • エラーレスポンスの詳細内容

4. kintone OAuth仕様

   • 認可エンドポイント: https://{subdomain}.cybozu.com/oauth2/authorization
   • トークンエンドポイント: https://{subdomain}.cybozu.com/oauth2/token
   • 認証方式: リクエストボディにclient_idとclient_secretを含める
   • レスポンス形式: JSON

5. デバッグモード 詳細なログを確認するには、開発サーバーを起動して実行できます：

   npm run dev
   

仕組みの概要

OAuthプロバイダー

OAuth Providerライブラリは、Cloudflare Workers向けのOAuth 2.1サーバー実装です。 このライブラリがOAuthフロー全体（トークン発行、検証、管理）を担当しています。具体的には：

• MCPクライアントの認証
• kintone OAuthサービスへの接続管理
• KVストレージでのトークン・認証状態の安全な保存

MCP Remote

MCP Remoteライブラリは、サーバーがクライアントにツールを提供できるようにします：

• クライアントとサーバー間の通信プロトコルを定義
• ツールの定義方法を提供
• リクエスト/レスポンスのシリアライズ・デシリアライズを管理
• クライアントとサーバー間のServer-Sent Events (SSE)接続を維持

MCP Server を使用するリスク

他人が作成・実装した MCP server を使用する際には一定のリスクがあることを必ず念頭において利用してください。

• kintone AIラボ と kintone用 MCP Server の現在地

「kintone」はサイボウズ株式会社の登録商標です。

ここに記載している内容は情報提供を目的としており、個別のサポートはできません。 設定内容についてのご質問やご自身の環境で動作しないといったお問い合わせをいただいても対応はできませんので、ご了承ください。