# DingTalk Calendar MCP Server

钉钉日程管理 MCP 服务器 - 通过 Model Context Protocol 管理钉钉日程

[English](#english) | [中文](#chinese)

<a name="english"></a>
## English

A Model Context Protocol (MCP) server for managing DingTalk calendar events. This server provides tools to create, update, delete, and query calendar events, manage attendees, and configure event reminders and recurrence rules.

### Features

- 📅 **Event Management**: Create, update, delete, and query calendar events
- 👥 **Attendee Management**: Add or remove event attendees
- ⏰ **Reminders**: Configure event reminders
- 🔁 **Recurrence**: Support for recurring events with various patterns
- 🔗 **Online Meetings**: Create events with DingTalk video meetings
- 🎨 **UI Customization**: Control the display of event detail page components
- 🔐 **Token Management**: Automatic token refresh with caching

### Available Tools

1. **createEvent** - Create a new calendar event
2. **updateEvent** - Update an existing event
3. **deleteEvent** - Delete an event
4. **getEvent** - Get details of a single event
5. **listEvents** - List events with time range filtering
6. **addAttendee** - Add attendees to an event
7. **removeAttendee** - Remove attendees from an event
8. **getAttendees** - Get the list of event attendees
9. **getCalendarView** - Query calendar view by time range

### Installation

```bash
# Clone the repository
git clone https://github.com/your-org/dingtalk-calendar-mcp
cd dingtalk-calendar-mcp

# Install dependencies
npm install

# Build the project
npm run build
```

### Configuration

1. Copy the environment variables template:
```bash
cp env.example .env
```

2. Edit `.env` file and add your DingTalk credentials:
```bash
# Option 1: Direct access token (for testing, valid for 2 hours)
DINGTALK_ACCESS_TOKEN=your_access_token_here

# Option 2: Client ID and Secret (recommended, auto-refresh)
DINGTALK_Client_ID=your_client_id_here
DINGTALK_Client_Secret=your_client_secret_here
```

### Usage

#### As MCP Server

Start the server:
```bash
npm start
# or
./start-mcp.sh
```

#### In Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "dingtalk-calendar": {
      "command": "node",
      "args": ["/path/to/dingtalk-calendar-mcp/dist/cli.js"],
      "env": {
        "DINGTALK_Client_ID": "your_client_id",
        "DINGTALK_Client_Secret": "your_client_secret"
      }
    }
  }
}
```

### Example Usage

#### Create an Event
```javascript
{
  "unionId": "user_union_id",
  "calendarId": "primary",
  "summary": "Team Meeting",
  "description": "Weekly team sync",
  "start": {
    "dateTime": "2024-01-15T10:00:00+08:00",
    "timeZone": "Asia/Shanghai"
  },
  "end": {
    "dateTime": "2024-01-15T11:00:00+08:00",
    "timeZone": "Asia/Shanghai"
  },
  "attendees": [
    {
      "id": "attendee_union_id",
      "isOptional": false
    }
  ],
  "reminders": [
    {
      "method": "dingtalk",
      "minutes": 15
    }
  ]
}
```

#### Create a Recurring Event
```javascript
{
  "unionId": "user_union_id",
  "calendarId": "primary",
  "summary": "Daily Standup",
  "start": {
    "dateTime": "2024-01-15T09:30:00+08:00",
    "timeZone": "Asia/Shanghai"
  },
  "end": {
    "dateTime": "2024-01-15T09:45:00+08:00",
    "timeZone": "Asia/Shanghai"
  },
  "recurrence": {
    "pattern": {
      "type": "daily",
      "interval": 1
    },
    "range": {
      "type": "endDate",
      "endDate": "2024-12-31T23:59:59+08:00"
    }
  }
}
```

### Development

```bash
# Run in development mode
npm run dev

# Build
npm run build

# Test with MCP Inspector
npm run inspector
```

---

<a name="chinese"></a>
## 中文

基于 Model Context Protocol (MCP) 的钉钉日程管理服务器。该服务器提供了创建、更新、删除和查询日程的工具，以及管理参与者、设置提醒和重复规则等功能。

### 功能特性

- 📅 **日程管理**：创建、更新、删除和查询日程
- 👥 **参与者管理**：添加或删除日程参与者
- ⏰ **提醒设置**：配置日程提醒
- 🔁 **重复日程**：支持多种重复模式的循环日程
- 🔗 **在线会议**：创建包含钉钉视频会议的日程
- 🎨 **UI自定义**：控制日程详情页组件的显示
- 🔐 **令牌管理**：自动刷新令牌并缓存

### 可用工具

1. **createEvent** - 创建新日程
2. **updateEvent** - 更新已有日程
3. **deleteEvent** - 删除日程
4. **getEvent** - 获取单个日程详情
5. **listEvents** - 列出日程，支持时间范围过滤
6. **addAttendee** - 添加日程参与者
7. **removeAttendee** - 删除日程参与者
8. **getAttendees** - 获取日程参与者列表
9. **getCalendarView** - 按时间范围查询日程视图

### 安装

```bash
# 克隆仓库
git clone https://github.com/your-org/dingtalk-calendar-mcp
cd dingtalk-calendar-mcp

# 安装依赖
npm install

# 构建项目
npm run build
```

### 配置

1. 复制环境变量模板：
```bash
cp env.example .env
```

2. 编辑 `.env` 文件，添加钉钉凭证：
```bash
# 方式一：直接使用访问令牌（用于测试，有效期2小时）
DINGTALK_ACCESS_TOKEN=your_access_token_here

# 方式二：使用客户端ID和密钥（推荐，自动刷新）
DINGTALK_Client_ID=your_client_id_here
DINGTALK_Client_Secret=your_client_secret_here
```

### 使用方法

#### 作为 MCP 服务器

启动服务器：
```bash
npm start
# 或
./start-mcp.sh
```

#### 在 Claude Desktop 中使用

添加到 Claude Desktop 配置文件（`~/Library/Application Support/Claude/claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "dingtalk-calendar": {
      "command": "node",
      "args": ["/path/to/dingtalk-calendar-mcp/dist/cli.js"],
      "env": {
        "DINGTALK_Client_ID": "your_client_id",
        "DINGTALK_Client_Secret": "your_client_secret"
      }
    }
  }
}
```

### 使用示例

#### 创建日程
```javascript
{
  "unionId": "用户的unionId",
  "calendarId": "primary",
  "summary": "团队会议",
  "description": "每周团队同步会",
  "start": {
    "dateTime": "2024-01-15T10:00:00+08:00",
    "timeZone": "Asia/Shanghai"
  },
  "end": {
    "dateTime": "2024-01-15T11:00:00+08:00",
    "timeZone": "Asia/Shanghai"
  },
  "attendees": [
    {
      "id": "参与者的unionId",
      "isOptional": false
    }
  ],
  "reminders": [
    {
      "method": "dingtalk",
      "minutes": 15
    }
  ]
}
```

#### 创建重复日程
```javascript
{
  "unionId": "用户的unionId",
  "calendarId": "primary",
  "summary": "每日站会",
  "start": {
    "dateTime": "2024-01-15T09:30:00+08:00",
    "timeZone": "Asia/Shanghai"
  },
  "end": {
    "dateTime": "2024-01-15T09:45:00+08:00",
    "timeZone": "Asia/Shanghai"
  },
  "recurrence": {
    "pattern": {
      "type": "daily",
      "interval": 1
    },
    "range": {
      "type": "endDate",
      "endDate": "2024-12-31T23:59:59+08:00"
    }
  }
}
```

### 开发

```bash
# 开发模式运行
npm run dev

# 构建
npm run build

# 使用 MCP Inspector 测试
npm run inspector
```

## API 权限要求

使用本服务需要在钉钉开发者后台为应用开通以下权限：
- 日历应用中日程写权限
- 日历应用中日程读权限

## 注意事项

1. 所有日程操作都需要提供用户的 `unionId`
2. `calendarId` 统一使用 `primary`，表示用户的主日历
3. 时间格式遵循 ISO-8601 标准
4. 全天日程使用 `date` 字段，非全天日程使用 `dateTime` 字段
5. 每次参与者操作最多支持 500 人

## License

MIT

## Contributing

欢迎提交 Issue 和 Pull Request！

## Support

如有问题，请提交 [Issue](https://github.com/your-org/dingtalk-calendar-mcp/issues)