Kintone MCP Server

kintone MCP Server (Python3) サンプル

kintone と連携するためのMCP (Model Context Protocol) サーバーのサンプル実装です。 このサーバーは、AI アシスタント（Claude等）が kintone のデータを読み取り、操作できるようにします。

主な特徴

• 🔐 セキュアな認証: APIトークン認証とパスワード認証の両方をサポート
• 📊 完全なCRUD操作: レコードの作成・読み取り・更新・削除が可能
• 📄 自動ページネーション: 大量のレコードを効率的に処理
• 🔍 高度なクエリ機能: kintoneのクエリ構文をフルサポート
• 📎 ファイル管理: ファイルのアップロード・ダウンロードに対応
• 💬 コメント機能: レコードへのコメント追加・取得
• 🔄 ステータス管理: プロセス管理のステータス更新
• 🚀 非同期処理: 高速なレスポンスと効率的なリソース使用
• 🛡️ 堅牢なエラー処理: 詳細なエラーメッセージと適切な例外処理
• 🌐 国際化対応: 多言語フィールドのサポート

利用可能なツール

レコード操作

コメント・ステータス操作

ファイル・アプリ管理

必要条件

• Python 3.12以上
• uv （推奨）
• kintone環境へのアクセス権限
• APIトークンまたはユーザー認証情報

MCPクライアント設定

Claude Desktop設定

Claude Desktopでこのサーバーを使用するには、設定ファイルに以下を追加してください。

設定ファイルの場所

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

uvxを使用（推奨）

GitHubから直接実行する設定：

{
  "mcpServers": {
    "kintone": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git",
        "kintone-mcp-server-python3"
      ],
      "env": {
        "KINTONE_DOMAIN": "your-subdomain.cybozu.com",
        "KINTONE_USERNAME": "your-username",
        "KINTONE_PASSWORD": "your-password"
      }
    }
  }
}

重要:

• KINTONE_DOMAINは必ず実際の値に置き換えてください（例: dev-demo.cybozu.com）
• 認証は、ユーザー名とパスワードの両方が指定されている場合はパスワード認証、そうでない場合はAPIトークン認証が使用されます
• 環境変数はclaude_desktop_config.json内に直接記載されます
• 設定変更後はClaude Desktopを再起動してください

VS Code設定

VS CodeのMCP拡張機能を使用する場合：

{
  "mcp.servers": {
    "kintone": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git",
        "kintone-mcp-server-python3"
      ],
      "env": {
        "KINTONE_DOMAIN": "your-subdomain.cybozu.com",
        "KINTONE_API_TOKEN": "your-api-token"
      }
    }
  }
}

複数環境の設定例

本番環境と開発環境を分けて管理する場合：

{
  "mcpServers": {
    "kintone-prod": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git",
        "kintone-mcp-server-python3"
      ],
      "env": {
        "KINTONE_DOMAIN": "your-subdomain.cybozu.com",
        "KINTONE_API_TOKEN": "prod-api-token"
      }
    },
    "kintone-dev": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git",
        "kintone-mcp-server-python3"
      ],
      "env": {
        "KINTONE_DOMAIN": "your-subdomain.cybozu.com",
        "KINTONE_USERNAME": "dev-user",
        "KINTONE_PASSWORD": "dev-password"
      }
    }
  }
}

設定のポイント

1. uvxの利点

   • 事前のインストールが不要
   • 常に最新版を実行
   • 依存関係の競合を回避

2. セキュリティの注意点

   • claude_desktop_config.jsonに kintoneへアクセスするための機密情報（ユーザー名, パスワード, APIトークン）を平文で保存する必要があります
   • このファイルを他人と共有しないでください
   • Gitリポジトリにコミットしないよう注意してください

トラブルシューティング

よくある問題と解決方法

接続エラー

Error: Failed to connect to kintone

解決方法:

1. KINTONE_DOMAINが正しいか確認（例: dev-demo.cybozu.com）
2. ネットワーク接続を確認
3. ファイアウォール設定を確認

認証エラー

Error: Authentication failed (401)

解決方法:

1. ユーザー名,パスワードやAPIトークンが正しいか確認
2. APIトークンに必要な権限があるか確認
3. アプリの設定でAPIトークンが有効になっているか確認

権限エラー

Error: Permission denied (403)

解決方法:

1. ユーザーにアプリへのアクセス権限があるか確認
2. APIトークンに必要な権限が付与されているか確認
3. レコードのアクセス権限を確認

デバッグモード

詳細なログを出力するには：

export LOG_LEVEL=DEBUG
uvx --from git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git kintone-mcp-server-python3

ソースコードをローカルインス