MCP服务器-谷歌表格看板
MCP（模型上下文协议）服务器，用于管理使用 Google 表格作为后端的 Kanban 框架中的任务。
特点
- 与 Google Sheets 集成使用 Google Sheets API v4 进行数据存储
- pydantic模型使用 Pydantic v2 验证数据
- 批次操作支持同时添加和更新多个任务
- 高级搜索按优先级、状态、上下文、项目和文本进行过滤
- 分页全面支持结果分页导航
- MCP 协议通过STDIO与MCP客户端兼容
配置
克劳德
在工程文件夹中运行以下命令 ：
claude mcp add --transport stdio kanban-sheets -- uv run -- --directory "caminho\projeto\sua\maquina" python main.py
可用工具
1. get_one_task -Tarefa Específica巴士
按任务 ID 和工程名称查找特定任务 。
参数 ：
project（必填）： 项目名称task_id（必填）： 唯一任务 ID
例如：
{
"project": "MCP Server Sheets",
"task_id": "TASK-001"
}回报（成功）：
{
"Projeto": "MCP Server Sheets",
"Task ID": "TASK-001",
"Task ID Root": "TASK-001",
"Sprint": "Sprint 1",
"Contexto": "Backend",
"Descrição": "Implementar busca avançada",
"Detalhado": "Adicionar filtros por prioridade, status e contexto",
"Prioridade": "Alta",
"Status": "Em Desenvolvimento",
"Data Criação": "2025-10-24 10:30:00",
"Data Solução": ""
}返回（未找到）：
{
"error": "Tarefa 'TASK-999' não encontrada no projeto 'MCP Server'"
}______________________________________________________________________
2. list_tasks 列出和搜索任务
列出并搜索具有高级过滤器和可选分页功能的电子表格任务。
参数 ：
filters（可选）：具有搜索条件的对象
- prioridade优先级列表（ 低、 正常、 高、 紧急） - status：要筛选的状态列表 - contexto：按上下文过滤（部分搜索，不区分大小写） - projeto按项目过滤（部分搜索，近似不敏感） - texto_busca描述和详细搜索（case-insensitive） - task_id：按特定任务ID搜索 - sprint：按冲刺筛选
pagination（可选）：COM对象page（页码）和page_size（每页项目）
例如：
// 1. Listar todas as tarefas (comportamento legado)
{}
// 2. Com paginação
{
"pagination": {
"page": 1,
"page_size": 20
}
}
// 3. Buscar tarefas de alta prioridade
{
"filters": {
"prioridade": ["Alta", "Urgente"]
}
}
// 4. Buscar tarefas em desenvolvimento com paginação
{
"filters": {
"status": ["Em Desenvolvimento"]
},
"pagination": {
"page": 1,
"page_size": 10
}
}
// 5. Buscar por texto na descrição
{
"filters": {
"texto_busca": "implementar API"
}
}
// 6. Combinar múltiplos filtros
{
"filters": {
"prioridade": ["Alta"],
"status": ["Todo", "Em Desenvolvimento"],
"contexto": "Backend",
"projeto": "MCP Server"
},
"pagination": {
"page": 1,
"page_size": 25
}
}返回（不分页）：
[
{
"Task ID": "TASK-001",
"Contexto": "Backend",
"Descrição": "...",
...
},
...
]返回（带分页）：
{
"tasks": [...],
"total_count": 45,
"page": 1,
"page_size": 25,
"total_pages": 2,
"has_next": true,
"has_previous": false
}______________________________________________________________________
3. add_task - 添加任务
向工作表添加新任务 。
参数 ：
task任务对象与所有字段
例如：
{
"task": {
"project": "MCP Server Sheets",
"task_id": "TASK-001",
"contexto": "Backend",
"descricao": "Implementar busca avançada",
"prioridade": "Alta",
"status": "Todo",
"task_id_root": "",
"sprint": "Sprint 1",
"detalhado": "Adicionar filtros por prioridade, status e contexto",
"data_criacao": "2025-10-24",
"data_solucao": ""
}
}______________________________________________________________________
4. update_task - 更新任务
以任务 ID 更新现有任务 。
参数 ：
task_id: 要更新的任务 IDupdates要更新的字段字典
例如：
{
"task_id": "TASK-001",
"updates": {
"Status": "Concluído",
"Data Solução": "2025-10-24"
}
}______________________________________________________________________
5. batch_add_tasks - 添加多任务
在一个操作中添加多个任务。
参数 ：
batch包含任务列表的 BatchTaskAdd 对象
例如：
{
"batch": {
"tasks": [
{
"project": "MCP Server",
"task_id": "TASK-001",
"contexto": "Backend",
"descricao": "Tarefa 1",
"prioridade": "Alta",
"status": "Todo"
},
{
"project": "MCP Server",
"task_id": "TASK-002",
"contexto": "Frontend",
"descricao": "Tarefa 2",
"prioridade": "Normal",
"status": "Todo"
}
]
}
}返回 ：
{
"success_count": 2,
"error_count": 0,
"details": [
{
"task_id": "TASK-001",
"status": "success",
"message": "Tarefa adicionada com sucesso"
},
{
"task_id": "TASK-002",
"status": "success",
"message": "Tarefa adicionada com sucesso"
}
]
}______________________________________________________________________
6. batch_update_tasks 多任务更新
在一次操作中更新多个任务。
参数 ：
batch包含更新列表的 BatchTaskUpdate 对象
例如：
{
"batch": {
"updates": [
{
"task_id": "TASK-001",
"fields": {"Status": "Concluído"}
},
{
"task_id": "TASK-002",
"fields": {"Prioridade": "Alta"}
}
]
}
}返回 ：
{
"success_count": 2,
"error_count": 0,
"details": [
{
"task_id": "TASK-001",
"status": "success",
"message": "Tarefa atualizada com sucesso"
},
{
"task_id": "TASK-002",
"status": "success",
"message": "Tarefa atualizada com sucesso"
}
]
}______________________________________________________________________
7. get_valid_configs - 获取有效设置
返回有效的状态和优先级值。
返回 ：
{
"valid_task_status": [
"Todo",
"Em Desenvolvimento",
"Impedido",
"Concluído",
"Cancelado",
"Não Relacionado",
"Pausado"
],
"valid_task_priorities": [
"Baixa",
"Normal",
"Alta",
"Urgente"
]
}______________________________________________________________________
数据模型
任务
{
"project": str, # Nome do Projeto (obrigatório)
"task_id": str, # ID único da tarefa (obrigatório)
"contexto": str, # Contexto da tarefa (obrigatório)
"descricao": str, # Descrição breve (obrigatório)
"prioridade": str, # Prioridade (obrigatório)
"status": str, # Status atual (obrigatório)
"task_id_root": str, # ID da tarefa raiz (opcional)
"sprint": str, # Sprint associada (opcional)
"detalhado": str, # Descrição detalhada (opcional)
"data_criacao": str, # Data de criação (opcional)
"data_solucao": str # Data de solução (opcional)
}BatchTaskAdd
{
"tasks": List[Task] # Lista de tarefas a serem adicionadas
}BatchTaskUpdate
{
"updates": List[TaskUpdate] # Lista de atualizações
}在哪里 任务更新 是 ：
{
"task_id": str, # ID da tarefa
"fields": dict # Campos a atualizar
}搜索筛选器
{
"prioridade": List[str], # Lista de prioridades
"status": List[str], # Lista de status
"contexto": str, # Filtro de contexto
"projeto": str, # Filtro de projeto
"texto_busca": str, # Busca de texto
"task_id": str, # ID específico
"sprint": str # Filtro de sprint
}分页路径
{
"page": int, # Número da página (mínimo: 1)
"page_size": int # Itens por página (1-500)
}考虑
{
"tasks": List[Dict], # Tarefas da página
"total_count": int, # Total de tarefas
"page": int, # Página atual
"page_size": int, # Itens por página
"total_pages": int, # Total de páginas
"has_next": bool, # Existe próxima página
"has_previous": bool # Existe página anterior
}______________________________________________________________________
配置
先决条件
- Python 3.13.5或更高级
- 启用 Google Sheets API 的 Google Cloud 帐户
- 档案
credentials.json服务 帐户 凭据
环境变量
创建文件 .env 通用域名格式：
KANBAN_SHEET_ID=seu_id_da_planilha_aqui
KANBAN_SHEET_NAME=Back-End # Nome da aba (padrão: "Back-End")安装
# Instalar dependências
uv sync
# Executar servidor
uv run main.pyMCP 客户端配置
添加到您的 MCP 客户端：
{
"mcpServers": {
"kanban-sheets": {
"command": "uv",
"args": ["run", "main.py"]
}
}
}______________________________________________________________________
电子表格结构
工作表必须有以下列（A 到 K）：
| 列 | 名称 | 描述 |
|---|---|---|
| 项目名称 | 项目名称 |
任务 ID 任务唯一 ID |C|根任务ID|根任务ID| | D | Sprint | Sprint 相关 | | 和 | 上下文 | 任务的上下文 | | F | 描述 | 简要描述 | | 详细 | 详细描述 | | H | 优先级 | 任务优先级 | |I |状态|状态自然| J 创建日期 创建日期 K 解决日期 解决日期
______________________________________________________________________
高级使用示例
查找所有紧急待办事宜
{
"filters": {
"prioridade": ["Urgente"],
"status": ["Todo", "Em Desenvolvimento"]
}
}列出具有分页功能的特定项目的任务
{
"filters": {
"projeto": "MCP Server"
},
"pagination": {
"page": 1,
"page_size": 50
}
}查找已停止或暂停的任务
{
"filters": {
"status": ["Impedido", "Pausado"]
}
}在描述中搜索关键字
{
"filters": {
"texto_busca": "API REST"
}
}______________________________________________________________________
使用的技术
- FastMCPMCP 服务器框架
- 派丹蒂克数据验证（v2.12.3）
- Google API Python客户端与 Google Sheets 集成
- 谷歌认证使用 Google Cloud 进行身份验证
______________________________________________________________________
测试
该项目包括一个使用pytest的完整测试套件。
测试结构
tests/
├── __init__.py
├── conftest.py # Fixtures compartilhadas
├── test_list_tasks.py # Testes para listagem e busca
├── test_add_task.py # Testes para adição de tarefas
├── test_update_task.py # Testes para atualização
└── test_batch_operations.py # Testes para operações em lote安装测试依赖项
# Instalar dependências de desenvolvimento
uv pip install -r requirements-dev.txt依赖关系包括：
pytest：测试框架pytest-asyncio支持异步测试pytest-cov：代码覆盖率pytest-mock模拟设施·全球之声
运行测试
# Executar todos os testes
uv run pytest
# Executar com cobertura de código
uv run pytest --cov
# Executar testes específicos
uv run pytest tests/test_list_tasks.py
# Executar testes com saída verbosa
uv run pytest -v
# Executar apenas testes de uma função específica
uv run pytest tests/test_list_tasks.py::test_list_tasks_all
# Gerar relatório de cobertura em HTML
uv run pytest --cov --cov-report=html
# O relatório será criado em htmlcov/index.html测试结构
测试使用Google Sheets API模拟，以免依赖于实际连接。主要设备包括：
mock_env_vars： 模拟环境变量mock_sheets_serviceGoogle Sheets 服务mock_credentials模仿 Google 凭据sample_sheet_data示例数据用于测试empty_sheet_data: 空工作表数据
测试覆盖
测试涵盖：
- list_tasks:
- 无过滤器列表 - 个别过滤器（优先级、状态、上下文等） - 多个过滤器组合 - 分页 - 错误案例
- add_task:
- 添加所有字段 - 添加最小字段 - 不同的优先级和状态 - 字段验证 - 错误处理
- update_task:
- 更新单个字段 - 更新多个字段 - 状态和优先级验证 - 任务未找到 - 错误处理
- batch_add_tasks和batchupdate_tasks:
- 成功批次操作 - 部分成功的操作 - 批量验证 - 错误处理
- get_valid_config:
- 返回有效设置 - 回报结构
测试示例
def test_list_tasks_with_priority_filter(mock_env_vars, mock_credentials_file,
mock_credentials, mock_get_sheets_service):
"""Testa filtro por prioridade."""
filters = SearchFilters(prioridade=["Alta"])
result = list_tasks(filters=filters)
assert isinstance(result, list)
assert len(result) == 1
assert result[0]["Task ID"] == "TASK-001"
assert result[0]["Prioridade"] == "Alta"pytest 配置
文件 pytest.ini 包含默认设置，包括：
- 测试发现标准
- 输出选项
- 代码覆盖设置
- 自定义标记
______________________________________________________________________
附加文档
______________________________________________________________________
许可证
此项目是用于管理 Google 工作表中的任务的 MCP 服务器。