kintone MCP Server (Python3)

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

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

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

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

{ "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を再起動してください

{ "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" } } } }

- claude_desktop_config.jsonに kintoneへアクセスするための機密情報（ユーザー名, パスワード, APIトークン）を平文で保存する必要があります
- このファイルを他人と共有しないでください
- Gitリポジトリにコミットしないよう注意してください
- KINTONE_DOMAINが正しいか確認（例: dev-demo.cybozu.com）
- ネットワーク接続を確認
- ファイアウォール設定を確認
- ユーザー名,パスワードやAPIトークンが正しいか確認
- APIトークンに必要な権限があるか確認
- アプリの設定でAPIトークンが有効になっているか確認
- ユーザーにアプリへのアクセス権限があるか確認
- APIトークンに必要な権限が付与されているか確認
- レコードのアクセス権限を確認

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

# リポジトリをクローン git clone https://github.com/r3-yamauchi/kintone-mcp-server-python3.git cd kintone-mcp-server-python3 # 依存関係をインストール pip install -e . # 実行 python -m kintone_mcp_server_python3

- app(必須): アプリID
- query(オプション): レコードをフィルタリングするクエリ文字列
- fields(オプション): 取得するフィールドコードのリスト
- limit(オプション): 取得する最大レコード数（デフォルト: 100、最大: 500）
- offset(オプション): ページネーション用のオフセット（デフォルト: 0）

{ "tool": "get_records", "arguments": { "app": 123, "query": "Status = \"Open\"", "fields": ["Title", "Status", "Created_datetime"], "limit": 100 } }

- app(必須): アプリID
- query(オプション): レコードをフィルタリングするクエリ文字列
- fields(オプション): 取得するフィールドコードのリスト

{ "tool": "get_all_records", "arguments": { "app": 123, "query": "Created_datetime > \"2024-01-01\"", "fields": ["Title", "Status"] } }

- name(オプション): アプリ名の部分一致検索（大文字小文字を区別しない）
- ids(オプション): 取得するアプリIDのリスト
- codes(オプション): 取得するアプリコードのリスト（完全一致、大文字小文字を区別）
- space_ids(オプション): スペースIDでフィルタリング
- limit(オプション): 取得する最大アプリ数（デフォルト: 100、最大: 100）
- offset(オプション): ページネーション用のオフセット（デフォルト: 0）

{ "tool": "get_apps", "arguments": { "name": "顧客", "limit": 50 } }

{ "apps": [ { "appId": "123", "code": "CUSTOMER_APP", "name": "顧客管理", "description": "顧客情報を管理するアプリです", "spaceId": "10", "createdAt": "2024-01-01T00:00:00Z", "creator": { "code": "user1", "name": "山田太郎" }, "modifiedAt": "2024-01-15T10:30:00Z", "modifier": { "code": "user2", "name": "佐藤花子" } } ], "count": 1 }

{ "tool": "get_record", "arguments": { "app": 123, "id": 456 } }

- app(必須): アプリID
- record(必須): フィールドコードと値のオブジェクト

{ "tool": "add_record", "arguments": { "app": 123, "record": { "Title": {"value": "新しいタスク"}, "Status": {"value": "未着手"}, "Assignee": {"value": [{"code": "user1"}]} } } }

- app(必須): アプリID
- records(必須): レコードデータの配列

{ "tool": "add_records", "arguments": { "app": 123, "records": [ { "Title": {"value": "タスク1"}, "Status": {"value": "未着手"} }, { "Title": {"value": "タスク2"}, "Status": {"value": "進行中"} } ] } }

- app(必須): アプリID
- id(オプション): レコードID（idまたはupdate_keyのいずれか必須）
- update_key(オプション): 更新キーとなるフィールドと値
- record(必須): 更新するフィールドと値
- revision(オプション): リビジョン番号（楽観的ロック用）

{ "tool": "update_record", "arguments": { "app": 123, "id": 456, "record": { "Status": {"value": "完了"}, "CompletedDate": {"value": "2024-12-07"} } } }

{ "tool": "update_records", "arguments": { "app": 123, "records": [ { "id": 456, "record": {"Status": {"value": "完了"}} }, { "id": 789, "record": {"Status": {"value": "保留"}} } ] } }

- app(必須): アプリID
- record(必須): レコードID
- order(オプション): ソート順（"asc" または "desc"、デフォルト: "desc"）
- offset(オプション): オフセット（デフォルト: 0）
- limit(オプション): 取得件数（最大10、デフォルト: 10）

{ "tool": "get_comments", "arguments": { "app": 123, "record": 456, "order": "desc", "limit": 5 } }

- app(必須): アプリID
- record(必須): レコードID
- text(必須): コメント本文
- mentions(オプション): メンション情報の配列

{ "tool": "add_comment", "arguments": { "app": 123, "record": 456, "text": "作業が完了しました。", "mentions": [ {"code": "user1", "type": "USER"} ] } }

- app(必須): アプリID
- id(必須): レコードID
- action(必須): アクション名
- assignee(オプション): 担当者のログイン名
- revision(オプション): リビジョン番号

{ "tool": "update_status", "arguments": { "app": 123, "id": 456, "action": "承認する", "assignee": "user2" } }

- app(必須): アプリID
- records(必須): ステータス更新データの配列

{ "tool": "update_statuses", "arguments": { "app": 123, "records": [ { "id": 456, "action": "承認する" }, { "id": 789, "action": "却下する" } ] } }

{ "tool": "upload_file", "arguments": { "file_path": "/path/to/document.pdf" } }

{ "fileKey": "20241207103000-1234567890ABCDEF" }

- file_key(必須): ファイルキー
- save_path(必須): 保存先のファイルパス

{ "tool": "download_file", "arguments": { "file_key": "20241207103000-1234567890ABCDEF", "save_path": "/path/to/save/document.pdf" } }

{ "tool": "get_app", "arguments": { "id": 123 } }

- app(必須): アプリID
- lang(オプション): 言語コード（例: "ja", "en"）

{ "tool": "get_form_fields", "arguments": { "app": 123, "lang": "ja" } }

{ "properties": { "Title": { "type": "SINGLE_LINE_TEXT", "code": "Title", "label": "タイトル", "required": true }, "Status": { "type": "DROP_DOWN", "code": "Status", "label": "ステータス", "options": { "未着手": {"label": "未着手", "index": "0"}, "進行中": {"label": "進行中", "index": "1"}, "完了": {"label": "完了", "index": "2"} } } }, "revision": "5" }

# リポジトリをクローン git clone https://github.com/r3-yamauchi/kintone-mcp-server-python3.git cd kintone-mcp-server-python3 # 仮想環境の作成（推奨） python -m venv venv source venv/bin/activate # macOS/Linux # venv\Scripts\activate # Windows # 開発用依存関係をインストール pip install -e ".[dev]" # 環境変数の設定 cp .env.example .env # .envファイルを編集して必要な設定を追加 # pre-commitフックの設定（推奨） pre-commit install

# すべてのテストを実行 pytest # カバレッジレポート付きでテスト実行 pytest --cov=kintone_mcp_server_python3 --cov-report=html # 特定のテストファイルを実行 pytest tests/test_auth.py # 特定のテストを実行 pytest tests/test_auth.py::test_api_token_auth -v

# コードフォーマット（Black） black src tests # リンティング（Ruff） ruff check src tests ruff check src tests --fix # 自動修正 # 型チェック（MyPy） mypy src # すべてのチェックを実行 make lint # Makefileがある場合 # または black src tests && ruff check src tests && mypy src

- バージョン番号を更新（pyproject.toml）
- 変更履歴を更新（CHANGELOG.md）
- テストを実行して成功を確認
- コード品質チェック：

black src tests ruff check src tests mypy src

git add . git commit -m "Release v0.1.0" git tag v0.1.0 git push origin main --tags

A: はい、MCPクライアントの設定で複数のサーバーインスタンスを定義できます。環境ごとに異なる名前（例：kintone-prod、kintone-dev）を付けてください。

A: はい、get_form_fieldsツールでlangパラメータを使用することで、英語（en）、中国語（zh）、スペイン語（es）などでフィールド情報を取得できます。

このプロジェクトはMITライセンスの下で公開されています。詳細はLICENSEファイルを参照してください。

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB