Garoon MCP Server

Garoon MCP服务器

将Garoon的REST API作为Model Context Protocol（MCP）服务器提供的项目。通过Claude Desktop等MCP客户端，可以利用Garoon的日程和消息功能。

提供与Garoon（Cybozu的群件解决方案）集成的模型上下文协议（MCP）服务器。

机能/ Features

• 计划管理:

- 浏览、制作自己的日程 - 查看其他用户的计划（支持targetType参数） - 事件菜单（类别）的指定对应

• 会议调度器/会议计划器:

- 自动查找空闲时间（检测到自己和对方都有空的时间） - 自动设置与会者会议 - 考虑营业时间和午休时间

• 用户搜索/用户搜索:

- 按名称或电子邮件地址搜索用户 - 检索其他用户的计划确认所需的用户ID

必要要件 / Requirements

• Python 3.10以上
• Garoon账户（需要REST API使用权限）
• 推荐或其他MCP客户端
• uv包管理器（推荐）

安装步骤/安装

1.克隆存储库/克隆存储库

git clone 
cd garoon-mcp-server

2.安装/安装依赖包

推奨: uv（快速、可靠的软件包管理器）

# uvのインストール（まだインストールしていない場合）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 依存パッケージのインストール
uv pip install -e .

或者，传统方法：

# 仮想環境の作成
python3 -m venv .venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate

# 依存パッケージのインストール
pip install -e .

3.环境变数の设定/ Configure environment variables

.env.example复制.env中描述的场景，使用下列步骤创建明细表，以便在概念设计中分析体量的周长。

cp .env.example .env

.env编辑/编辑文件 .env 文件：

GAROON_BASE_URL=https://your-subdomain.cybozu.com
GAROON_USERNAME=your.email@company.com
GAROON_PASSWORD=your_password_here
LOG_LEVEL=INFO

4.认证测试/测试authentication

python3 test_auth.py

认证成功后，将显示以下消息：

✅ Authentication successful!
✅ API call successful, response: {...}

Claude Desktopでの使用方法 / Using with Claude Desktop

1.编辑Claude Desktop配置文件/编辑Claude Desktop config

编辑位于以下位置的配置文件：

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

2.添加MCP服务器设置/添加MCP服务器配置

{
  "mcpServers": {
    "garoon": {
      "command": "/path/to/garoon-mcp-server/.venv/bin/python",
      "args": ["/path/to/garoon-mcp-server/main.py"],
      "env": {
        "GAROON_BASE_URL": "https://your-subdomain.cybozu.com",
        "GAROON_USERNAME": "your.email@company.com",
        "GAROON_PASSWORD": "your_password_here"
      }
    }
  }
}

注意 / Note:

• /path/to/garoon-mcp-server替换为实际项目路径
• 对于Windows： C:\\path\\to\\garoon-mcp-server\\.venv\\Scripts\\python.exe

3. Claude Desktopの再起动/ Restart Claude Desktop

完全退出Claude Desktop并重新启动，以反映设置。

注意：由于VSCode扩展也使用相同的配置文件，因此可同时用于Claude Desktop/Claude Code。

4. 使用例 / Usage examples

可以在Claude Desktop中使用Garoon功能：

确认自己的日程：

今日のスケジュールを教えて

计划：

明日の10時から11時に「会議」という予定を作成して

检查其他用户的计划：

山田さんの明日のスケジュールを確認して

用户搜索：

「田中」という名前のユーザーを探して

会议空闲时间搜索和设置： 🆕

山田さんと明日の午後、1時間会議したい。空いている時間は？

14:00-15:00で「プロジェクト会議」という会議を設定してください

使用Docker设置（可选）/Using Docker（Optional）

也可以使用Docker运行MCP服务器。

1.构建/构建Docker映像

docker build -t garoon-mcp-server .

2. Claude Desktop设定でDockerを使用/ Use Docker in Claude Desktop config

{
  "mcpServers": {
    "garoon": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GAROON_BASE_URL",
        "-e",
        "GAROON_USERNAME",
        "-e",
        "GAROON_PASSWORD",
        "garoon-mcp-server:latest"
      ],
      "env": {
        "GAROON_BASE_URL": "https://your-subdomain.cybozu.com",
        "GAROON_USERNAME": "your.email@company.com",
        "GAROON_PASSWORD": "your_password_here"
      }
    }
  }
}

使用Docker的优点/Benefits of using Docker

• ✅ Python环境隔离
• ✅ 易于管理依赖关系
• ✅ 易于部署

认证方式/ Authentication

该MCP服务器是Garoon REST API的X-Cybozu-Authorization使用页眉进行身份验证。通过Base64编码发送用户名和密码。

此MCP服务器使用 X-Cybozu-Authorization 用于Garoon REST API身份验证的头。用户名和密码采用Base64编码。

可用工具/可用工具

get_schedule

获取自己或其他用户的日程表/Get schedule events from Garoon for yourself or other users。

参数：

• start_date （required）：开始日（YYYY-MM-DD形式）/ Start date in YYYY-MM-DD format
• end_date （required）：终了日（YYYY-MM-DD形式）/ End date in YYYY-MM-DD format
• user_id （optional）：用户ID（指定时获取其他用户的调度，省略时为自己的调度）/User ID to get schedule for (if not specified, returns your own schedule)

注意: user_id时褪色为此颜色targetType="user"将自动添加参数。

create_schedule

创建新的计划事件/创建a new schedule event in Garoon。

参数：

• subject （required）：事件标题/Event subject/title
• start_datetime （required）：开始日时（ISO形式）/ Start datetime in ISO format
• end_datetime （required）：终了日时（ISO形式）/ End datetime in ISO format
• description （optional）：事件描述/Event description
• event_menu （optional）：活动菜单（例如：“会议”，“外出”）/Event menu/category.Defaults to“-----”if omitted。

注意：登录用户（GAROON_USERNAME），模板名称将采用不同的格式。

搜索用户

按名称或其他条件搜索Garoon用户/搜索for users in Garoon by name or other criteria。

参数：

• query （required）：搜索查询（用户名、电子邮件地址等）/搜索query（user name，email，etc.）
• limit （optional）：最大捕获数（默认值：20）/Maximum number of results to return（default:20）

使用例：在查看其他用户的计划之前，您可以使用此工具搜索用户标识。

find_available_time🆕

查找自己和指定用户都有空的时间段/Find available time slots for a meeting with another user.

参数：

• user_id （required）：对方的用户ID/Other user’s Garoon user ID
• start_date （required）：検索开始日（YYYY-MM-DD）/ Search start date
• end_date （required）：検索终了日（YYYY-MM-DD）/ Search end date
• duration_minutes （required）：必要な会议时间（分）/ Required meeting duration in minutes
• start_time （optional）：营业开始时间（HH:MM，默认值：09:00）/Daily start time
• end_time （optional）：营业结束时间（HH:MM，默认值：18:00）/Daily end time
• exclude_lunch （optional）：午休除外（默认值：true）/Exclude lunch time12:00-13:00

返回值：最大3件の空き时间候补（开始・终了时刻）

创建会议

创建带参与者的会议日程表/创建a meeting with attendees。

参数：

• subject （required）：会议标题/Meeting subject/title
• start_datetime （required）：开始日时（ISO形式）/ Start datetime（ISO format）
• end_datetime （required）：终了日时（ISO形式）/ End datetime（ISO format）
• attendee_ids （required）：参与者的用户ID列表/列表
• description （optional）：会议の说明/ Meeting description
• event_menu （optional）：活动菜单（例如：“会议”，“外出”）/Event menu/category.Defaults to“-----”if omitted。

注意：登录用户（GAROON_USERNAME），模板名称将采用不同的格式。attendee_ids 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

故障排除/故障排除

如果出现验证错误/验证错误

• 请确认Garoon的用户名和密码是否正确
• 请确认Garoon的基本URL是否正确（不需要末尾的斜线）
• 请确认Garoon账户是否有效，允许使用API

如果MCP服务器未启动/服务器won’t start

• 检查Python路径是否正确
• 请检查虚拟环境是否已启用
• 请确认是否安装了从属软件包

如果在用户搜索或获取调度时出现错误/用户search or schedule retrieval errors

• “未找到指定的URI路径”错误:

- 检查Garoon API的版本（需要云版或封装版4.10或更高版本） - 请确认用户帐户是否具有API使用权限

• 无法获取其他用户的调度:

- user_id参数和targetType同时需要参数（本MCP服务器将自动设置） - 无法获取没有查看权限的时间表

安全说明/安全注释

⚠️ 重要 / Important:

• .env绝对不要将文件提交给git .env 文件到git
• 不要共享包含密码和API密钥的文件/Don't share files containing passwords or API keys
• 在生产环境中，请考虑使用更安全的认证方法（如OAuth）Consider using more secure authentication methods (OAuth, etc.) in production

文件配置/文件结构

garoon-mcp-server/
├── main.py                        # MCPサーバのメインエントリーポイント
├── garoon_client.py               # Garoon APIクライアント
├── tests/
│   ├── test_main.py               # MCPツールのユニットテスト
│   └── test_garoon_client.py      # Garoon APIクライアントのユニットテスト
├── pyproject.toml                 # プロジェクト設定と依存関係
├── .env                           # 環境変数（gitに含めない）
├── .env.example                   # 環境変数のテンプレート
├── .gitignore                     # Git除外設定
└── README.md                      # このファイル

开発/ Development

安装/安装与开发相关的软件包

# uvを使用する場合
uv pip install -e ".[dev]"

# または、pipを使用する場合
pip install -e ".[dev]"

代码格式/代码格式

uv run black .
# または: black .

类型检查

uv run mypy main.py garoon_client.py
# または: mypy main.py garoon_client.py

运行/运行测试

uv run pytest
# または: pytest

変更履歴 / Changelog

v0.3.0

添加的功能：

• ✅ eventMenu支持参数（create_schedule / create_meeting）
• ✅ 自动将登录用户添加到参与者（GAROON_USERNAME），模板名称将采用不同的格式
• ✅ create_meeting消除重复参与者

错误修复：

• eventType正确"REGULAR"修改为（错误： "NORMAL"）
• subject / notes的请求格式符合API规范（直接字符串）
• start / end的timeZone添加字段
• attendees的，之id字段正确code修改为字段

v0.2.0版本

添加的功能：

• ✅ 空き时间自动検索机能（find_available_time工具）

- 自动检测自己和对方都有空的时间 - 考虑营业时间和午休时间 - 最多提供3个候选人

• ✅ 会议创建（create_meeting工具）
• ✅ 支持时区指定（GAROON_TIMEZONE环境变数）

v0.1.0

添加的功能：

• ✅ Garoon REST API统合（X-Cybozu-Authorization认证）
• ✅ 日程管理（获取、制作）
• ✅ 用户搜索功能（search_users工具）
• ✅ 检查其他用户的计划（targetType支持参数）

许可证/许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持/支持

如果出现问题，请创建Issue。

有关问题和疑问，请在GitHub上创建问题。