Google Tasks MCP Server

Google Tasks MCP 服务

Google Tasks 的 Model Context Protocol（MCP）服务，允许 AI 助手通过 MCP 协议与 Google Tasks 交互。

功能

• 列出、创建、更新和删除任务列表
• 列出、搜索、创建、更新、删除和移动任务
• 支持通过父子关系组织任务
• 查看任务详细信息
• 清除已完成的任务
• OAuth2 身份验证并自动刷新令牌
• 并行 API 请求，提升性能
• 提供 TypeScript 接口，确保类型安全
• 全面的错误处理
• 通过 MCP 与 AI 助手集成

安装

# Clone the repository
git clone https://github.com/overlay-one/google-tasks-mcp-server.git
cd google-tasks-mcp-server

# Install dependencies
pnpm install

# Build the project
pnpm build

配置

设置 Google Cloud API 访问权限

1. 在 Google Cloud Console 中创建项目。
2. 启用 Google Tasks API：
   • 前往 API 库
   • 搜索“Tasks API”
   • 点击“启用”
3. 创建 OAuth 2.0 凭据：
   • 前往“凭据”
   • 点击“创建凭据”，然后选择“OAuth 客户端 ID”
   • 将“Web 应用”选作应用类型
   • 添加重定向 URI（例如，http://localhost:3000/oauth2callback）
   • 创建完成后，记下客户端 ID 和客户端密钥

环境配置

1. 将 .env.example 复制为 .env：

cp .env.example .env

2. 使用 Google API 凭据编辑 .env 文件：

# Required credentials
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
REDIRECT_URI=http://localhost:3000/oauth2callback

# Optional tokens (if you already have them)
# ACCESS_TOKEN=your-access-token
# REFRESH_TOKEN=your-refresh-token

# Optional server configuration
# LOG_LEVEL=info     # Options: error, warn, info, debug

身份验证方式

此服务支持两种身份验证方式：

1. 环境变量：在 .env 文件中设置 ACCESS_TOKEN 和 REFRESH_TOKEN
2. 凭据文件：服务可以将令牌存储在 .credentials.json 文件中

此服务包含自动刷新令牌的处理机制。访问令牌过期时，服务将：

1. 自动使用刷新令牌获取新的访问令牌
2. 在内存中更新凭据
3. 将更新后的令牌保存到 .credentials.json（如果使用基于文件的存储）

使用方法

启动服务

# Production mode
pnpm start

# Development mode (with auto-reloading)
pnpm dev

与 Claude Desktop 配合使用

Claude Desktop 可以与此 MCP 服务集成，直接访问 Google Tasks。借助此集成，你可以通过与 Claude 的自然语言对话来管理任务。

使用 Claude 管理 Google Tasks 的好处

• 自然语言任务管理：使用日常语言创建、搜索和整理任务
• 上下文理解：当你将到期日期说成“明天”或“下周”时，Claude 能理解你的意思
• 任务优先级建议：请 Claude 帮助整理任务并确定优先级
• 智能搜索：通过上下文和含义查找任务，而不仅限于精确关键词
• 批量操作：请 Claude 帮助你一次创建或修改多个任务
• 日程安排建议：Claude 可以根据现有任务建议合适的到期日期
• 任务摘要：获取多个列表中任务的简明摘要
• 每日规划：请 Claude 根据当前任务帮助你规划一天

设置说明

设置集成的方法如下：

1. 启动 Google Tasks MCP 服务：

   pnpm start
   

   服务将通过标准输入/输出通道（stdio）运行。

2. 启动已连接 MCP 服务的 Claude Desktop：

   claude mcp --command "node /path/to/google-tasks-mcp-server/dist/index.js"
   

   将 /path/to/google-tasks-mcp-server 替换为实际安装路径。

3. 或者：创建配置文件： 在主目录或项目目录中创建名为 claude.yaml 的文件：

   mcp:
     command: node /path/to/google-tasks-mcp-server/dist/index.js
   

   然后只需运行 claude，即可使用配置好的 MCP 服务。

4. 在 Claude Desktop 中： 连接后，Claude 就可以通过自定义 MCP 资源和工具访问你的 Google Tasks。你可以让 Claude： -“显示我的任务列表” -“创建一个名为‘完成项目报告’的新任务” -“查找所有与会议相关的任务” -“将我的‘审核文档’任务标记为已完成”

Claude 会根据你的请求，通过 MCP 服务访问 Google Tasks 数据。

与 Claude 的对话示例

连接后，你可以与 Claude 进行以下对话：

列出任务：

You: Show me all my tasks
Claude: I'll retrieve your tasks from Google Tasks.
[Claude uses task.list tool]
Here are your current tasks:
- Complete project documentation (Due: 2025-05-10)
- Schedule team meeting (Due: Not set)
- Review quarterly report (Due: 2025-05-15)

创建任务：

You: Create a new task called "Send follow-up email" due tomorrow at 3 PM
Claude: I'll create that task for you.
[Claude uses task.create tool]
I've created a new task:
Title: Send follow-up email
Due: 2025-05-06T15:00:00Z
Status: needsAction

搜索任务：

You: Find all tasks related to "meeting"
Claude: I'll search for tasks containing "meeting".
[Claude uses task.search tool]
I found 2 tasks related to "meeting":
- Schedule team meeting (Due: Not set)
- Prepare meeting agenda (Due: 2025-05-08)

管理任务列表：

You: Create a new task list called "Personal Projects"
Claude: I'll create that task list for you.
[Claude uses tasklist.create tool]
I've created a new task list named "Personal Projects".
Would you like me to add any tasks to this list?

高级使用场景

以下是使用 Claude 管理 Google Tasks 的一些高级方式：

项目规划

You: I need to plan a website launch. Can you help me create tasks for it?
Claude: I'd be happy to help plan your website launch. Let me create a task list and relevant tasks.
[Claude uses tasklist.create and task.create tools]
I've created a new task list "Website Launch" with the following tasks:
1. Finalize website content (Due: 1 week from now)
2. Complete design review (Due: 10 days from now)
3. Run final QA tests (Due: 2 weeks from now)
4. Prepare marketing materials (Due: 2 weeks from now)
5. Configure analytics (Due: 3 days before launch)
6. Launch website (Due: 3 weeks from now)
Would you like me to add more specific tasks?

任务整理与优先级排序

You: I have too many tasks. Can you help me prioritize them?
Claude: I'll help you organize and prioritize your tasks.
[Claude uses task.list tool]
Based on your current tasks, here's a suggested prioritization:

High Priority (Complete today):
- Submit quarterly report (Due: Today)
- Call client about project delay (Due: Today)

Medium Priority (Complete this week):
- Prepare presentation (Due: In 3 days)
- Review team metrics (Due: In 5 days)

Low Priority (Can be scheduled later):
- Research new tools (Due: Next week)
- Update documentation (Due: In 2 weeks)

Would you like me to update the due dates to reflect these priorities?

定期任务管理

You: What tasks should I focus on today?
Claude: Let me check your tasks due today or overdue.
[Claude uses task.list and task.search tools]
Here are the tasks you should focus on today:

Due Today:
- Prepare client meeting agenda
- Submit expense report

Overdue:
- Follow up on pending approvals (Due yesterday)

Upcoming Soon:
- Project proposal draft (Due tomorrow)

Should I mark any of these as completed?

Claude Desktop 集成故障排除

如果将 Claude Desktop 连接到 Google Tasks MCP 服务时遇到问题：

1. 身份验证问题：

   • 确保 .env 文件中包含正确的 CLIENT_ID、CLIENT_SECRET 和 REDIRECT_URI
   • 检查 .env 或 .credentials.json 中是否有有效的刷新令牌
   • 如有需要，通过 Google OAuth 流程重新生成令牌

2. 连接问题：

   • 连接 Claude 前，确认服务已通过 pnpm start 运行
   • 检查 claude mcp --command 中的路径是否正确
   • 如果使用配置文件，请确保 YAML 语法有效

3. 找不到命令：

   • 确保 Claude Desktop CLI 位于 PATH 中
   • 尝试使用 Claude 可执行文件的完整路径

4. MCP 协议错误：

   • 服务遇到内部错误时通常会出现此类错误
   • 查看服务日志，了解具体错误的详细信息
   • 确保使用兼容版本的 Claude Desktop 和 MCP SDK

API 参考

资源

服务通过自定义 URI 方案提供资源：

任务列表资源

• gtasklists:///：列出所有任务列表
• gtasklists:///{taskListId}：按 ID 访问特定任务列表

任务资源

• gtasks:///：列出所有任务列表中的任务
• gtasks:///default：列出默认任务列表中的任务
• gtasks:///{taskId}：按 ID 访问特定任务
• gtasks:///{taskListId}/tasks/{taskId}：访问特定任务列表中的特定任务

工具

该服务通过 MCP 工具支持以下操作：

任务列表管理

工具	描述	必需参数	可选参数
tasklist.list	列出所有任务列表	无	maxResults
tasklist.get	按 ID 获取任务列表	id	无
tasklist.create	创建任务列表	title	无
tasklist.update	更新任务列表	id、title	无
tasklist.delete	删除任务列表	id	无

任务管理

工具	描述	必需参数	可选参数
task.search	按标题或备注搜索任务	query	taskListId
task.list	列出所有任务	无	taskListId、cursor
task.get	按 ID 获取任务	id	taskListId
task.create	创建任务	title	taskListId、notes、due、status、parent
task.update	更新现有任务	id	taskListId、title、notes、status、due、parent
task.move	移动任务（更改父级或位置）	id	taskListId、parent、previous
task.delete	删除任务	id	taskListId
task.clear	清除已完成的任务	无	taskListId

操作示例

创建任务

{
  "name": "task.create",
  "arguments": {
    "title": "Complete project documentation",
    "notes": "Include API reference and setup instructions",
    "due": "2025-05-10T00:00:00.000Z",
    "status": "needsAction"
  }
}

搜索任务

{
  "name": "task.search",
  "arguments": {
    "query": "documentation",
    "taskListId": "MTIzNDU2Nzg5MA"
  }
}

开发

项目结构

• src/index.ts：主服务实现和 MCP 协议处理程序
• src/Tasks.ts：任务和任务列表资源及操作的实现
• src/types.ts：用于请求/响应处理的 TypeScript 接口
• test/：服务组件的单元测试

TypeScript 类型

项目使用 TypeScript 接口确保类型安全。主要接口包括：

• 请求参数类型：所有工具参数类型的 TypeScript 接口
  • TaskCreateParams、TaskUpdateParams、TaskSearchParams 等
• 资源类型：资源表示形式的接口
  • TaskResource、TaskListResource
• 实用类型：用于操作 Google Tasks API 的辅助类型

这些接口有助于确保向 Google Tasks API 传递参数和处理响应时的类型安全。

错误处理

该服务实现了一致的错误处理系统，该系统：

1. 将 HTTP 错误代码映射到相应的 MCP 错误代码
2. 提供包含操作上下文的详细错误消息
3. 适当处理并行 API 调用中的错误

性能优化

该服务在涉及多个任务列表的操作中使用并行 API 调用：

• 在 TaskResources.list() 和 TaskActions._list() 中，并行获取多个列表中的任务
• 即使部分任务列表请求失败，也能正确合并结果
• 这显著提升了拥有多个任务列表的用户的使用性能

测试

项目使用 Node.js 内置测试运行器构建了测试框架：

# Run all tests (this will first build the TypeScript code)
pnpm test

# Run tests in watch mode for development
pnpm test:watch

首次运行测试前，请确保已安装依赖项：

pnpm install

测试套件包括：

• 身份验证测试：验证令牌刷新处理
• 任务操作测试：验证任务 API 功能
• 错误处理测试：确保正确处理错误

测试使用 JavaScript 编写，并针对编译后的 TypeScript 代码运行，以确保生产代码按预期工作。测试使用模拟依赖项，因此测试期间不会发起真实的 Google API 调用。

构建

pnpm build

在开发模式下运行

pnpm dev

许可证

Apache-2.0