kintone MCP Server (Python3)

kintone MCP Server (Python3) 样本

kintone 与…合作MCP (Model Context Protocol) 服务器的示例实现。 此服务器包含：AI 助手（Claude等）kintone 查看项目中可用的所有族。

  

主要特征

• 🔐 安全认证: API支持令牌认证和密码认证
• 📊 完整CRUD操作：允许创建、读取、更新和删除记录
• 📄 自动分页：有效处理大量记录
• 🔍 高级查询功能: kintone完全支持查询语法
• 📎 文件管理：支持文件上载下载
• 💬 注释功能：添加/检索记录注释
• 🔄 状态管理：更新流程管理状态
• 🚀 非同期処理：快速响应和高效资源使用
• 🛡️ 坚固的错误处理：详细的错误消息和适当的异常处理
• 🌐 国際化対応：支持多语言字段

可用工具

记录操作

｜工具名称｜说明｜主要用途｜ |---------|-----|---------| | get_record ｜获取单个记录｜获取特定记录的详细信息｜ | get_records 获取记录列表（带分页）｜查找和获取符合条件的记录｜ | get_all_records ｜自动获取所有记录｜批量获取大量记录（自动分页）｜ | add_record ｜添加单个记录｜创建新记录｜ | add_records 批量添加多条记录（最多100条） | update_record ｜更新单个记录｜更新现有记录的信息｜ | update_records 多条记录的批量更新（最多100条）

注释状态操作

｜工具名称｜说明｜主要用途｜ |---------|-----|---------| | get_comments ｜获取记录注释｜确认交流历史记录｜ | add_comment 向记录添加注释 | update_status 记录状态更新工作流进度 | update_statuses 多条记录的状态成批更新｜高效工作流处理｜

文件应用程序管理

｜工具名称｜说明｜主要用途｜ |---------|-----|---------| | upload_file 上传文件｜注册附件｜ | download_file 下载文件，获取附件 | get_app 获取应用程序信息确认应用程序设置 | get_apps 搜索和获取应用程序列表搜索可用应用程序 | get_form_fields 获取表单字段设置｜理解应用程序结构｜

必要条件

• Python 3.12以上
• uv （推奨）
• kintone环境访问权限
• API令牌或用户凭据

MCP客户端设置

Claude Desktop设定

Claude Desktop要在中使用此服务器，请在配置文件中添加以下内容。

配置文件位置

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %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优点

- 无需预先安装 - 始终运行最新版本 - 避免依赖冲突

1. 安全注意事项

- 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

本地安装源代码

# リポジトリをクローン
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

使用例

基本用法

获取记录

带有页面对齐功能kintone从应用程序中获取记录。

参数：

• 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
  }
}

获取所有记录

kintone从应用程序中获取所有记录（自动处理页码）。

参数：

• app （必须）：应用程序ID
• query （可选）：用于筛选记录的查询字符串
• fields （可选）：要检索的字段代码列表

使用例:

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

获取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
}

获取记录

获取单个记录。

参数：

• app （必须）：应用程序ID
• id （必需）：记录ID

使用例:

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

add_record

kintone在应用程序中添加单个记录。

参数：

• app （必须）：应用程序ID
• record （必需）：字段代码和值对象

使用例:

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

add_records

批量添加多个记录（最多100条）。

参数：

• app （必须）：应用程序ID
• records （必需）：排列记录数据

使用例:

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

update_record

更新单个记录。

参数：

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

update_records

批量更新多个记录（最多100条）。

参数：

• app （必须）：应用程序ID
• records （必需）：排列更新数据

使用例:

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

update_status

更新记录状态。

参数：

• app （必须）：应用程序ID
• id （必需）：记录ID
• action （必需）：操作名称
• assignee （可选）：联系人登录名
• revision （可选）：修订版本号

使用例:

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

update_status

批量更新多条记录的状态（最多100条）。

参数：

• app （必须）：应用程序ID
• records （必需）：状态更新数据数组

使用例:

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

上传文件

打开文件kintone中所述修改相应参数的值。

参数：

• file_path （必需）：要上载的文件路径

使用例:

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

响应示例：

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

下载文件

kintone中所述修改相应参数的值。

参数：

• file_key （必需）：文件键
• save_path （必需）：目标文件路径

使用例:

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

获取app

获取应用程序的详细信息。

参数：

• id （必须）：应用程序ID

使用例:

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

get_form_fields

获取应用程序的表单字段设置。

参数：

• 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

发放步骤

1. 更新版本号（pyproject.toml）
2. 変更履歴を更新（CHANGELOG.md）
3. 运行测试以确认成功
4. 代码质量检查：

   black src tests
   ruff check src tests
   mypy src

1. GitHub推入：

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

1. GitHub在中创建发行说明（可选）

常见问题解答

Q: 多个kintone可以同时使用环境吗？

A: 是的MCP客户端设置允许您定义多个服务器实例。每个环境都有不同的名称（例如：kintone-prod、kintone-dev），模板名称将采用不同的格式。

Q: 可以用日语以外的语言获取字段信息吗？

A: 是的get_form_fields在动态输入提示中单击lang通过使用参数，可以使用英语（en）、中文（zh）、西班牙语（es）等获取字段信息。

著者

r3 yamauchi

许可证

这个项目MIT在许可证下公开。了解更多信息许可证请参见文件。

MCP Server 使用的风险

由他人制作、实施的MCP server 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

• kintone AI实验室和kintone用于MCP Server 所在地

「kintone」是赛博股份有限公司的注册商标。

此处描述的内容旨在提供信息，不能提供单独的支持。 关于设定内容的问题和在自己的环境中不动作的咨询也不能对应，请谅解。