kintone MCP Server (Python3)
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kintone MCP Server (Python3) List all records in app 10 where the status is 'In Progress'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
kintone MCP Server (Python3) サンプル
kintone と連携するためのMCP (Model Context Protocol) サーバーのサンプル実装です。 このサーバーは、AI アシスタント(Claude等)が kintone のデータを読み取り、操作できるようにします。
主な特徴
🔐 セキュアな認証: APIトークン認証とパスワード認証の両方をサポート
📊 完全なCRUD操作: レコードの作成・読み取り・更新・削除が可能
📄 自動ページネーション: 大量のレコードを効率的に処理
🔍 高度なクエリ機能: kintoneのクエリ構文をフルサポート
📎 ファイル管理: ファイルのアップロード・ダウンロードに対応
💬 コメント機能: レコードへのコメント追加・取得
🔄 ステータス管理: プロセス管理のステータス更新
🚀 非同期処理: 高速なレスポンスと効率的なリソース使用
🛡️ 堅牢なエラー処理: 詳細なエラーメッセージと適切な例外処理
🌐 国際化対応: 多言語フィールドのサポート
Related MCP server: Kintone MCP Server
利用可能なツール
レコード操作
ツール名 | 説明 | 主な用途 |
| 単一レコードの取得 | 特定のレコードの詳細情報を取得 |
| レコード一覧の取得(ページネーション付き) | 条件に合うレコードを検索・取得 |
| 全レコードの自動取得 | 大量レコードの一括取得(自動ページネーション) |
| 単一レコードの追加 | 新規レコードの作成 |
| 複数レコードの一括追加(最大100件) | バッチ処理による効率的なレコード作成 |
| 単一レコードの更新 | 既存レコードの情報更新 |
| 複数レコードの一括更新(最大100件) | バッチ処理による効率的なレコード更新 |
コメント・ステータス操作
ツール名 | 説明 | 主な用途 |
| レコードのコメント取得 | コミュニケーション履歴の確認 |
| レコードへのコメント追加 | メンション付きコメントの投稿 |
| レコードのステータス更新 | ワークフローの進行 |
| 複数レコードのステータス一括更新 | 効率的なワークフロー処理 |
ファイル・アプリ管理
ツール名 | 説明 | 主な用途 |
| ファイルのアップロード | 添付ファイルの登録 |
| ファイルのダウンロード | 添付ファイルの取得 |
| アプリ情報の取得 | アプリ設定の確認 |
| アプリ一覧の検索・取得 | 利用可能なアプリの探索 |
| フォームフィールド設定の取得 | アプリ構造の理解 |
必要条件
Python 3.12以上
uv (推奨)
kintone環境へのアクセス権限
APIトークンまたはユーザー認証情報
MCPクライアント設定
Claude Desktop設定
Claude Desktopでこのサーバーを使用するには、設定ファイルに以下を追加してください。
設定ファイルの場所
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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"
}
}
}
}設定のポイント
uvxの利点
事前のインストールが不要
常に最新版を実行
依存関係の競合を回避
セキュリティの注意点
claude_desktop_config.jsonに kintoneへアクセスするための機密情報(ユーザー名, パスワード, APIトークン)を平文で保存する必要がありますこのファイルを他人と共有しないでください
Gitリポジトリにコミットしないよう注意してください
トラブルシューティング
よくある問題と解決方法
接続エラー
Error: Failed to connect to kintone解決方法:
KINTONE_DOMAINが正しいか確認(例: dev-demo.cybozu.com)ネットワーク接続を確認
ファイアウォール設定を確認
認証エラー
Error: Authentication failed (401)解決方法:
ユーザー名,パスワードやAPIトークンが正しいか確認
APIトークンに必要な権限があるか確認
アプリの設定でAPIトークンが有効になっているか確認
権限エラー
Error: Permission denied (403)解決方法:
ユーザーにアプリへのアクセス権限があるか確認
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使用例
基本的な使い方
get_records
ページネーション機能付きでkintoneアプリからレコードを取得します。
パラメータ:
app(必須): アプリIDquery(オプション): レコードをフィルタリングするクエリ文字列fields(オプション): 取得するフィールドコードのリストlimit(オプション): 取得する最大レコード数(デフォルト: 100、最大: 500)offset(オプション): ページネーション用のオフセット(デフォルト: 0)
使用例:
{
"tool": "get_records",
"arguments": {
"app": 123,
"query": "Status = \"Open\"",
"fields": ["Title", "Status", "Created_datetime"],
"limit": 100
}
}get_all_records
kintoneアプリから全レコードを取得します(ページネーションを自動処理)。
パラメータ:
app(必須): アプリIDquery(オプション): レコードをフィルタリングするクエリ文字列fields(オプション): 取得するフィールドコードのリスト
使用例:
{
"tool": "get_all_records",
"arguments": {
"app": 123,
"query": "Created_datetime > \"2024-01-01\"",
"fields": ["Title", "Status"]
}
}get_apps
kintoneアプリの情報を検索・取得します。
パラメータ:
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
}get_record
単一のレコードを取得します。
パラメータ:
app(必須): アプリIDid(必須): レコードID
使用例:
{
"tool": "get_record",
"arguments": {
"app": 123,
"id": 456
}
}add_record
kintoneアプリに単一のレコードを追加します。
パラメータ:
app(必須): アプリIDrecord(必須): フィールドコードと値のオブジェクト
使用例:
{
"tool": "add_record",
"arguments": {
"app": 123,
"record": {
"Title": {"value": "新しいタスク"},
"Status": {"value": "未着手"},
"Assignee": {"value": [{"code": "user1"}]}
}
}
}add_records
複数のレコードを一括で追加します(最大100件)。
パラメータ:
app(必須): アプリIDrecords(必須): レコードデータの配列
使用例:
{
"tool": "add_records",
"arguments": {
"app": 123,
"records": [
{
"Title": {"value": "タスク1"},
"Status": {"value": "未着手"}
},
{
"Title": {"value": "タスク2"},
"Status": {"value": "進行中"}
}
]
}
}update_record
単一のレコードを更新します。
パラメータ:
app(必須): アプリIDid(オプション): レコードID(idまたはupdate_keyのいずれか必須)update_key(オプション): 更新キーとなるフィールドと値record(必須): 更新するフィールドと値revision(オプション): リビジョン番号(楽観的ロック用)
使用例:
{
"tool": "update_record",
"arguments": {
"app": 123,
"id": 456,
"record": {
"Status": {"value": "完了"},
"CompletedDate": {"value": "2024-12-07"}
}
}
}update_records
複数のレコードを一括更新します(最大100件)。
パラメータ:
app(必須): アプリIDrecords(必須): 更新データの配列
使用例:
{
"tool": "update_records",
"arguments": {
"app": 123,
"records": [
{
"id": 456,
"record": {"Status": {"value": "完了"}}
},
{
"id": 789,
"record": {"Status": {"value": "保留"}}
}
]
}
}get_comments
レコードのコメントを取得します。
パラメータ:
app(必須): アプリIDrecord(必須): レコードIDorder(オプション): ソート順("asc" または "desc"、デフォルト: "desc")offset(オプション): オフセット(デフォルト: 0)limit(オプション): 取得件数(最大10、デフォルト: 10)
使用例:
{
"tool": "get_comments",
"arguments": {
"app": 123,
"record": 456,
"order": "desc",
"limit": 5
}
}add_comment
レコードにコメントを追加します。
パラメータ:
app(必須): アプリIDrecord(必須): レコードIDtext(必須): コメント本文mentions(オプション): メンション情報の配列
使用例:
{
"tool": "add_comment",
"arguments": {
"app": 123,
"record": 456,
"text": "作業が完了しました。",
"mentions": [
{"code": "user1", "type": "USER"}
]
}
}update_status
レコードのステータスを更新します。
パラメータ:
app(必須): アプリIDid(必須): レコードIDaction(必須): アクション名assignee(オプション): 担当者のログイン名revision(オプション): リビジョン番号
使用例:
{
"tool": "update_status",
"arguments": {
"app": 123,
"id": 456,
"action": "承認する",
"assignee": "user2"
}
}update_statuses
複数レコードのステータスを一括更新します(最大100件)。
パラメータ:
app(必須): アプリIDrecords(必須): ステータス更新データの配列
使用例:
{
"tool": "update_statuses",
"arguments": {
"app": 123,
"records": [
{
"id": 456,
"action": "承認する"
},
{
"id": 789,
"action": "却下する"
}
]
}
}upload_file
ファイルをkintoneにアップロードします。
パラメータ:
file_path(必須): アップロードするファイルのパス
使用例:
{
"tool": "upload_file",
"arguments": {
"file_path": "/path/to/document.pdf"
}
}レスポンス例:
{
"fileKey": "20241207103000-1234567890ABCDEF"
}download_file
kintoneからファイルをダウンロードします。
パラメータ:
file_key(必須): ファイルキーsave_path(必須): 保存先のファイルパス
使用例:
{
"tool": "download_file",
"arguments": {
"file_key": "20241207103000-1234567890ABCDEF",
"save_path": "/path/to/save/document.pdf"
}
}get_app
アプリの詳細情報を取得します。
パラメータ:
id(必須): アプリID
使用例:
{
"tool": "get_app",
"arguments": {
"id": 123
}
}get_form_fields
アプリのフォームフィールド設定を取得します。
パラメータ:
app(必須): アプリIDlang(オプション): 言語コード(例: "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 srcGitHubにプッシュ:
git add . git commit -m "Release v0.1.0" git tag v0.1.0 git push origin main --tagsGitHubでリリースノートを作成(オプション)
FAQ
Q: 複数のkintone環境を同時に使用できますか?
A: はい、MCPクライアントの設定で複数のサーバーインスタンスを定義できます。環境ごとに異なる名前(例:kintone-prod、kintone-dev)を付けてください。
Q: 日本語以外の言語でフィールド情報を取得できますか?
A: はい、get_form_fieldsツールでlangパラメータを使用することで、英語(en)、中国語(zh)、スペイン語(es)などでフィールド情報を取得できます。
著者
r3-yamauchi
ライセンス
このプロジェクトはMITライセンスの下で公開されています。詳細はLICENSEファイルを参照してください。
MCP Server を使用するリスク
他人が作成・実装した MCP server を使用する際には一定のリスクがあることを必ず念頭において利用してください。
「kintone」はサイボウズ株式会社の登録商標です。
ここに記載している内容は情報提供を目的としており、個別のサポートはできません。 設定内容についてのご質問やご自身の環境で動作しないといったお問い合わせをいただいても対応はできませんので、ご了承ください。
Available Tools
17 toolsadd_commentC
Add a comment to a record
Inputs: app (required), record (required), text (required), mentions.
add_recordC
Add a single record to a kintone app
Inputs: app (required), record (required).
add_recordsC
Add multiple records to a kintone app (max 100 records)
Inputs: app (required), records (required).
download_fileC
Download a file from kintone
Inputs: file_key (required), save_path (required).
get_all_recordsA
Get all records from a kintone app (handles pagination automatically)
Inputs: app (required), query, fields.
get_appC
Get app information
Inputs: id (required).
get_appsC
Get kintone apps information by name or other filters
Inputs: name, ids, codes, space_ids, +2 more.
get_commentsC
Get comments for a record
Inputs: app (required), record (required), order, offset, +1 more.
get_form_fieldsB
Get form fields configuration
Inputs: app (required), lang.
get_query_language_docB
Get comprehensive documentation about kintone query language syntax
Inputs: no named parameters.
get_recordC
Get a single record from a kintone app
Inputs: app (required), id (required).
get_recordsC
Get records from a kintone app
Inputs: app (required), query, fields, limit, +1 more.
update_recordC
Update a single record in a kintone app
Inputs: app (required), record (required), id, update_key, +1 more.
update_recordsC
Update multiple records in a kintone app (max 100 records)
Inputs: app (required), records (required).
update_statusC
Update the status of a record
Inputs: app (required), id (required), action (required), assignee, +1 more.
update_statusesC
Update the status of multiple records (max 100)
Inputs: app (required), records (required).
upload_fileC
Upload a file to kintone
Inputs: file_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools have distinct purposes targeting specific resources and actions, such as add_record vs. update_record or get_record vs. get_records. However, get_all_records and get_records could cause confusion as both retrieve records, though the former handles pagination automatically, which is a subtle but potentially ambiguous distinction for agents.
All tool names follow a consistent verb_noun pattern with clear, descriptive verbs like add, get, update, download, and upload. The naming is uniform across all 17 tools, using snake_case throughout without any deviations or mixed conventions.
With 17 tools, the count is slightly high but reasonable for a kintone server covering CRUD operations, file handling, comments, and app management. It feels comprehensive without being overly bloated, though it borders on the upper limit of a well-scoped set.
The tool set provides complete coverage for the kintone domain, including full CRUD for records (add, get, update), batch operations, file upload/download, comment management, app and form field retrieval, and status updates. There are no obvious gaps, and agents can handle typical workflows without dead ends.
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Connect AI agents to ProductNow's context engine to search, create, review, and act.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAllows you to explore and manipulate kintone data using AI tools such as Claude Desktop!10MIT
- AlicenseCqualityDmaintenanceA Model Context Protocol server that enables Claude and other AI assistants to access and update Kintone data through natural language commands, supporting operations like record management, file handling, app administration, and space collaboration.7910AGPL 3.0
- FlicenseNot gradedqualityDmaintenanceEnables secure interaction with kintone through OAuth authentication, supporting record operations, app configuration management, file operations, and access control without storing API keys locally.-
- AlicenseAqualityDmaintenanceA lightweight MCP server that connects AI assistants to Kintone applications for managing records and automating business workflows. It enables secure authentication and natural language interaction for performing CRUD operations and querying data within the Kintone platform.101MIT