AI导哈

任务管理服务器

一个通过FastMCP提供完整Google Tasks API访问的模型上下文协议（MCP）服务器，支持创建、读取、更新、删除和管理Google Tasks。

  • by jessdejong
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 jessdejong/google-tasks-mcp-server

使用说明

Google 任务 MCP 服务器

一个全面的模型上下文协议（MCP）服务器，通过FastMCP提供对Google Tasks API的全面访问。您可以在任何MCP兼容的客户端上创建、读取、更新、删除和管理您的Google任务。

特点/特性

🔍 读取操作

  • 获取任务从Google任务中检索任务，并应用筛选选项
  • 获取任务通过ID获取单个任务
  • 列出任务列表查看您Google帐户中所有可用的任务列表
  • 搜索任务按内容、截止日期和状态筛选任务

✏️（钢笔/铅笔） 写入操作

  • 创建任务向任意任务列表添加新任务
  • 更新任务修改现有任务属性（标题、备注、截止日期、状态）
  • 完成任务将任务标记为已完成或未完成
  • 删除任务从任务列表中移除任务
  • 移动任务重新排序任务或在父任务之间移动任务
  • 创建任务列表创建新的任务列表

🔐 安全与可靠性

  • OAuth 2.0 认证使用Google实现基于令牌的安全认证
  • 自动令牌刷新自动处理令牌过期
  • 环境检测在交互式和非交互式环境中均能正常工作
  • 全面错误处理详细的错误信息和日志记录

设置

1. 安装依赖项

# Using uv (recommended)
uv sync

# Or using pip
pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib fastmcp

2. Google Cloud Console 设置

  1. 前往 Google Cloud 控制台
  2. 创建一个新项目或选择一个现有项目
  3. 启用Google任务API：
    • 前往“APIs和服务”>“库”
    • 搜索“Google Tasks API”
    • 点击“启用”
  4. 创建凭据：
    • 前往“APIs 与服务”>“凭据”
    • 点击“创建凭据”>“OAuth 客户端 ID”
    • 选择“桌面应用程序”
    • 下载JSON文件并将其保存为 credentials.json 在项目根目录下

3. 首次运行

当你首次运行服务器时，它会：

  1. 打开一个浏览器窗口进行Google身份验证
  2. 请您登录并授予权限
  3. 保存认证令牌以供将来使用
# Run the server
python main.py

# Or using uv
uv run python main.py

使用方法

服务器提供 10款综合工具 用于管理您的Google任务：

📋（清单/列表） 任务管理工具

get_tasks

从特定任务列表中检索任务，并应用过滤选项。

参数：

  • tasklist_id (字符串，默认：“@default”)：任务列表的ID
  • max_results （整数，默认值：100）：要返回的任务的最大数量
  • show_completed （布尔值，默认：false）：包含已完成的任务
  • show_deleted (布尔值，默认: false): 是否包含已删除的任务

get_task

通过任务ID获取单个任务。

参数：

  • task_id （字符串，必填）：要检索的任务的ID
  • tasklist_id (字符串，默认值：“@default”)：任务列表的ID

create_task

在任务列表中创建一个新任务。

参数：

  • title (字符串，必填)：新任务的标题
  • tasklist_id (字符串，默认值：“@default”)：任务列表的ID
  • notes （字符串，可选）：任务的备注
  • due （字符串，可选）：截止日期，采用RFC 3339格式
  • parent （字符串，可选）：子任务的父任务ID
  • position （字符串，可选）：插入任务的位置

update_task

更新现有任务的属性。

参数：

  • task_id （字符串，必填）：要更新的任务的ID
  • tasklist_id (字符串，默认：“@default”)：任务列表的ID
  • title （字符串，可选）：新标题
  • notes （字符串，可选）：新备注
  • due （字符串，可选）：新的截止日期
  • status （字符串，可选）：新状态（“needsAction”或“completed”）
  • parent （字符串，可选）：新的父任务ID
  • position （字符串，可选）：新位置

complete_task

将任务标记为已完成或未完成。

参数：

  • task_id （字符串，必填）：任务的ID
  • tasklist_id (字符串，默认：“@default”)：任务列表的ID
  • completed (布尔值，默认: true): 是否标记为已完成

delete_task

从任务列表中删除一个任务。

参数：

  • task_id (字符串，必填)：要删除的任务的ID
  • tasklist_id (字符串，默认：“@default”)：任务列表的ID

move_task

将任务移动到新位置或重新指定其父级。

参数：

  • task_id （字符串，必填）：要移动的任务的ID
  • tasklist_id (字符串，默认：“@default”)：任务列表的ID
  • parent （字符串，可选）：新的父任务ID
  • previous (字符串，可选)：要在此任务之后放置的任务的ID

search_tasks

按内容和日期搜索并筛选任务。

参数：

  • tasklist_id (字符串，默认：“@default”)：任务列表的ID
  • query (字符串，可选)：在标题/备注中搜索的文本
  • include_completed (布尔值，默认：false)：是否包含已完成的任务
  • include_deleted (布尔值，默认：false)：是否包含已删除的任务
  • due_before （字符串，可选）：筛选在此日期之前到期的任务
  • due_after （字符串，可选）：过滤在此日期之后到期的任务
  • max_results （整数，默认值：100）：最大结果数量

📁 文件夹 任务列表管理工具

list_tasklists

列出您Google账户中所有可用的任务列表。

参数： 无

create_tasklist

创建一个新的任务列表。

参数：

  • title （字符串，必填）：新任务列表的名称

MCP客户端集成

Gemini CLI 配置

添加到您的Gemini设置中（.gemini/settings.json):

{
  "mcpServers": [
    {
      "name": "google-tasks",
      "command": "uv",
      "args": ["run", "python", "/absolute/path/to/run_server.py"]
    }
  ]
}

注： 替换 /absolute/path/to/ 使用您实际的仓库路径。或者，使用 start_server.sh 作为命令。

Gemini CLI 中的示例命令

@google-tasks list my task lists
@google-tasks get my tasks
@google-tasks create task "Buy groceries" in "My Tasks"
@google-tasks complete task "task-id-here"
@google-tasks search tasks for "meeting"
@google-tasks create tasklist "Work Projects"

配置

服务器使用以下配置：

  • 凭证文件： credentials.json （从Google Cloud Console下载）
  • 令牌文件： token.json （首次认证后自动生成）
  • 范围（或“作用域”）: https://www.googleapis.com/auth/tasks （完全读/写访问权限）
  • 交通STDIO（用于MCP协议通信）

错误处理

服务器包含了针对以下方面的全面错误处理：

  • 认证失败
  • API速率限制
  • 网络连接问题
  • 无效的任务列表ID
  • 缺少凭据

测试

测试MCP服务器工具

运行集成测试以验证所有工具是否正常工作：

# Test all MCP tools
uv run python test_all_tools.py

# Test individual server functions
uv run python test_server.py

使用Gemini进行测试

# Test server directly
python3 run_server.py

发展

为服务器扩展额外功能：

  1. 使用以下方式添加新工具 @mcp.tool 装饰器
  2. 在工具函数中实现Google Tasks API调用
  3. 如有需要，请更新身份验证范围
  4. 使用您的Google任务账户进行测试
  5. 用新工具的文档更新此README文件

项目结构

google-tasks-mcp-server/
├── server.py              # Main MCP server implementation
├── main.py                # Entry point
├── run_server.py          # Environment wrapper (used by Gemini)
├── start_server.sh        # Shell wrapper for MCP clients
├── test_all_tools.py      # Integration test suite
├── test_server.py         # Unit tests
├── debug_auth.py          # Authentication debugging
├── credentials.json       # Google OAuth credentials (user-provided)
├── token.json            # Authentication token (auto-generated)
└── pyproject.toml        # Dependencies

安全注意事项

  • 保持你的 credentials.json 文件要保存好，切勿提交到版本控制系统中
  • 这个（或那个，具体根据上下文确定） token.json 该文件包含您的身份验证令牌，也应妥善保管
  • 服务器对Google Tasks使用完全的读写权限（创建/更新/删除操作所需）
  • 所有API调用均通过HTTPS进行，并使用OAuth 2.0进行身份验证

故障排除

常见问题

  1. **“凭证文件未找到”**确保 credentials.json 位于项目根目录
  2. **“认证失败”**删除 token.json 并重新进行身份验证
  3. **“权限不足”**删除 token.json 并重新进行身份验证（权限从只读更改为读/写）
  4. **“未找到任务列表”**确保你的Google任务账户中有任务
  5. API未启用在Google Cloud Console中启用Google Tasks API
  6. **“未找到MCP服务器”**检查您的Gemini CLI配置和服务器路径

认证问题

如果您遇到认证问题：

# Delete the old token and re-authenticate
rm token.json
python main.py
# Complete the browser authentication flow

日志

服务器会记录重要信息以辅助调试。请查看控制台输出以获取详细的错误信息。

寻求帮助

许可证

这个项目是开源的，并遵循MIT许可证发布。

相关 MCP