使用说明

📋 Trello MCP服务器

生产准备就绪 模型上下文协议（MCP）服务器 Trello与AI代理和Claude Desktop无缝集成。几分钟内即可部署到Google Cloud Run！

🎯 这是什么

此MCP服务器提供 11个全面的Trello工具 允许AI代理：

管理公告板、列表和卡片
创建和更新内容
搜索和组织项目
指派团队成员
跟踪进度和截止日期

非常适合： 项目管理自动化、人工智能驱动的任务组织和智能Trello工作流。

✨ 主要特点

🔐 交互式登录系统新

基于浏览器的身份验证 -自动弹出Trello登录页面
会话凭据缓存 -8小时自动缓存，无磁盘存储
可选凭据 -第一个请求提示，后续请求使用缓存
缺省安全 -每次会话从不要求提供凭据超过一次
请参阅： QUICK_START_LOGIN.txt | INTERACTIVE_LOGIN_GUIDE.md

🔒 安全第一

按请求凭据 -API密钥从未存储
输入验证 使用Pydantic模式
多租户保险箱 -按用户凭据隔离
速率限制 -遵守Trello的API限值（要求300个/10秒）

🚀 生产就绪

Google Cloud Run已优化 -快速启动，优雅关机
健康检查 - /health 监控端点
结构化日志记录 -云日志的JSON格式
错误处理 -全面的错误信息
Docker容器化 -多阶段构建<200MB

🛠️ 完整的工具集

董事会管理：列出、获取、创建、更新公告板
列表管理：获取列表，创建新列表
卡片管理：获取、创建、更新卡片、分配成员、搜索

📦 包含什么

trello_mcp_server/
├── main.py              # HTTP server (156 lines)
├── mcp_server.py        # MCP protocol handler (148 lines)  
├── trello_client.py     # Trello API wrapper (340 lines)
├── tools.py             # 11 Trello tools (522 lines)
├── schemas.py           # Pydantic models (40 lines)
├── config.py            # Configuration (22 lines)
├── logging_config.py    # Structured logging (47 lines)
├── Dockerfile           # Multi-stage container
├── cloudbuild.yaml      # CI/CD pipeline
├── requirements.txt     # Dependencies
├── .dockerignore        # Build optimization
├── START_HERE.txt       # Quick orientation
├── QUICKSTART.md        # 5-minute deployment
└── README.md            # This file

总计：约1300行生产代码

🚀 快速开始

1.获取Trello证书

# Go to: https://trello.com/app-key
# Copy: API Key + Token

2.部署到云端运行

cd trello_mcp_server
export PROJECT_ID="your-gcp-project"

# Enable APIs
gcloud services enable run.googleapis.com cloudbuild.googleapis.com

# Build & Deploy
gcloud builds submit --tag gcr.io/$PROJECT_ID/trello-mcp:latest .
gcloud run deploy trello-mcp \
  --image gcr.io/$PROJECT_ID/trello-mcp:latest \
  --region us-central1 \
  --allow-unauthenticated \
  --memory 512Mi

3.测试您的服务器

curl https://your-service-url/health
# Expected: {"status":"healthy","service":"trello-mcp",...}

完整部署指南：参见 QUICKSTART.md

🛠️ 全部11个工具

类别	工具	描述
板子	`list_boards`	列出所有用户板
	`get_board`	获取详细的董事会信息
	`create_board`	创建新板
	`update_board`	更新电路板设置
列表	`get_lists`	将所有列表放在板上
	`create_list`	创建新列表
卡片	`get_cards`	从棋盘或列表中获取卡片
	`create_card`	创建新卡
	`update_card`	更新现有卡
	`add_member_to_card`	将成员分配到卡
	`search_cards`	全面搜索卡片

📋 使用示例

MCP协议集成

所有工具均遵循JSON-RPC 2.0 MCP协议：

POST /mcp
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "list_boards", 
    "arguments": {
      "api_key": "your-trello-api-key",
      "token": "your-trello-token"
    }
  }
}

创建新董事会

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 2,
  "params": {
    "name": "create_board",
    "arguments": {
      "api_key": "your-api-key",
      "token": "your-token", 
      "name": "Q4 Project Planning",
      "desc": "Planning board for Q4 initiatives",
      "prefs": {
        "permissionLevel": "org",
        "background": "blue"
      }
    }
  }
}

搜索紧急卡

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 3,
  "params": {
    "name": "search_cards",
    "arguments": {
      "api_key": "your-api-key",
      "token": "your-token",
      "query": "urgent OR priority:high",
      "limit": 50
    }
  }
}

创建和分配卡片

{
  "jsonrpc": "2.0",
  "method": "tools/call", 
  "id": 4,
  "params": {
    "name": "create_card",
    "arguments": {
      "api_key": "your-api-key",
      "token": "your-token",
      "name": "Implement new feature",
      "list_id": "list-id-here",
      "desc": "Detailed description of the feature requirements",
      "due": "2024-12-31T23:59:59Z",
      "members": ["member-id-1", "member-id-2"]
    }
  }
}

🔗 集成指南

⭐ Claude桌面集成

步骤1：下载代理服务器

# Get the proxy server that connects to Cloud Run
curl -o ~/trello_mcp_server.py https://raw.githubusercontent.com/Skai-IT/mcp-trello/main/trello_mcp_server.py
chmod +x ~/trello_mcp_server.py

步骤2：安装依赖项

pip3 install httpx

步骤3：配置Claude桌面

文件位置： ~/Library/Application Support/Claude/claude_desktop_config.json

添加此配置：

{
  "mcpServers": {
    "trello-mcp": {
      "command": "python3",
      "args": ["/Users/YOUR_USERNAME/trello_mcp_server.py"],
      "env": {
        "TRELLO_MCP_URL": "https://trello-mcp-116435607783.us-central1.run.app",
        "TRELLO_MCP_TYPE": "cloud_run"
      }
    }
  }
}

⚠️ 重要提示： 替换 YOUR_USERNAME 使用您的主目录（运行 echo $HOME)

步骤4:重新启动克劳德桌面

完全关闭克劳德
重新打开它
Trello MCP现在应该可用了

步骤5：验证连接

在Claude中，尝试：

List my Trello boards

Claude将连接到您的Trello帐户并显示您的董事会。

VS代码集成

配置文件

文件位置： ~/.vscode/settings.json

将此添加到您的设置中：

{
  "mcp": {
    "mcpServers": {
      "trello-mcp": {
        "command": "python3",
        "args": ["/Users/YOUR_USERNAME/trello_mcp_server.py"],
        "env": {
          "TRELLO_MCP_URL": "https://trello-mcp-116435607783.us-central1.run.app",
          "TRELLO_MCP_TYPE": "cloud_run"
        }
      }
    }
  }
}

替换 YOUR_USERNAME 使用您的主目录。

验证连接

重新启动VS代码
打开开发人员控制台： Cmd + Shift + J （Mac）
查找：“MCP服务器已连接”
无错误=✅ 成功！

光标集成

步骤1：获取代理服务器

与Claude Desktop相同-下载 trello_mcp_server.py

步骤2：安装依赖项

pip3 install httpx

步骤3：配置游标

文件位置： ~/.cursor/settings.json 或 ~/.config/Cursor/User/settings.json

{
  "mcp": {
    "mcpServers": {
      "trello-mcp": {
        "command": "python3",
        "args": ["/Users/YOUR_USERNAME/trello_mcp_server.py"],
        "env": {
          "TRELLO_MCP_URL": "https://trello-mcp-116435607783.us-central1.run.app"
        }
      }
    }
  }
}

步骤4：重新启动游标

完全关闭光标
重新打开它
Trello MCP已准备好使用

Cline（VS代码扩展）集成

Cline是VS Code的自主AI代理。

配置

添加到您的VS代码 settings.json:

{
  "mcp": {
    "mcpServers": {
      "trello-mcp": {
        "command": "python3",
        "args": ["/Users/YOUR_USERNAME/trello_mcp_server.py"],
        "env": {
          "TRELLO_MCP_URL": "https://trello-mcp-116435607783.us-central1.run.app"
        }
      }
    }
  }
}

与Cline一起使用

在VS代码中打开Cline
开始新任务
问Cline：“使用Trello MCP创建一个名为‘Q4规划’的董事会”
Cline将使用MCP工具与Trello进行交互

LM工作室集成

LM Studio是一个支持MCP的本地LLM接口。

配置

文件位置： ~/.lm-studio/mcp-servers.json

{
  "servers": [
    {
      "name": "trello-mcp",
      "type": "stdio",
      "command": "python3",
      "args": ["/Users/YOUR_USERNAME/trello_mcp_server.py"],
      "env": {
        "TRELLO_MCP_URL": "https://trello-mcp-116435607783.us-central1.run.app"
      }
    }
  ]
}

Zed集成

Zed是一个支持MCP的高性能代码编辑器。

配置

文件位置： ~/.config/zed/settings.json

{
  "mcp_servers": {
    "trello-mcp": {
      "command": "python3",
      "args": ["/Users/YOUR_USERNAME/trello_mcp_server.py"],
      "env": {
        "TRELLO_MCP_URL": "https://trello-mcp-116435607783.us-central1.run.app"
      }
    }
  }
}

自定义AI集成

Python客户端示例

import httpx
import json

class TrelloMCPClient:
    def __init__(self, service_url):
        self.service_url = service_url
        self.client = httpx.Client()
    
    def call_tool(self, tool_name, **params):
        """Call a Trello MCP tool"""
        request = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": tool_name,
            "params": params
        }
        
        response = self.client.post(
            f"{self.service_url}/mcp",
            json=request
        )
        return response.json()
    
    def list_boards(self):
        """List all Trello boards"""
        return self.call_tool("list_boards", {})
    
    def create_card(self, board_id, list_id, name, description=""):
        """Create a new Trello card"""
        return self.call_tool("create_card", {
            "board_id": board_id,
            "list_id": list_id,
            "name": name,
            "description": description
        })

# Usage
client = TrelloMCPClient("https://trello-mcp-116435607783.us-central1.run.app")
boards = client.list_boards()
print(boards)

JavaScript/Node.js客户端示例

const fetch = require('node-fetch');

class TrelloMCPClient {
  constructor(serviceUrl) {
    this.serviceUrl = serviceUrl;
  }

  async callTool(toolName, params) {
    const request = {
      jsonrpc: '2.0',
      id: 1,
      method: toolName,
      params: params
    };

    const response = await fetch(`${this.serviceUrl}/mcp`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(request)
    });

    return response.json();
  }

  async listBoards() {
    return this.callTool('list_boards', {});
  }

  async createCard(boardId, listId, name, description = '') {
    return this.callTool('create_card', {
      board_id: boardId,
      list_id: listId,
      name: name,
      description: description
    });
  }
}

// Usage
const client = new TrelloMCPClient('https://trello-mcp-116435607783.us-central1.run.app');
client.listBoards().then(boards => console.log(boards));

集成汇总表

工具	类型	配置文件	状态
Claude桌面版	🤖 AI代理	`claude_desktop_config.json`	✅ 完全支持
VS Code	📝 编辑	`.vscode/settings.json`	✅ 完全支持
光标	📝 编辑	`.cursor/settings.json`	✅ 完全支持
克莱恩	🤖 VS代码扩展	`.vscode/settings.json`	✅ 完全支持
LM工作室	🤖 本地法学硕士	`.lm-studio/mcp-servers.json`	✅ 支持
泽德	📝 编辑	`.config/zed/settings.json`	✅ 支持
自定义Python	🔧 客户	N/A	✅ 提供的示例
自定义Node.js	🔧 客户	N/A	✅ 提供的示例

开始使用每个工具

适用于克劳德桌面

✅ 下载代理服务器
✅ 安装httpx
✅ 将配置添加到 claude_desktop_config.json
✅ 重新启动克劳德
🎯 开始使用Trello工具！

用于VS代码/光标

✅ 下载代理服务器
✅ 安装httpx
✅ 将配置添加到settings.json
✅ 重新启动编辑器
🎯 在编辑器中打开MCP工具！

用于自定义集成

✅ 获取服务URL
✅ 使用提供的客户端代码
✅ 通过JSON-RPC调用工具
🎯 集成到您的应用程序中！

故障排除集成

问题：“MCP服务器未连接”

验证代理服务器是否正在运行： python3 ~/trello_mcp_server.py
检查配置文件语法（验证JSON）
确保路径正确： echo $HOME
重新启动应用程序

问题：“凭据错误”

第一个工具调用将提示进行身份验证
浏览器应自动向Trello打开
提示时复制API密钥和令牌
凭据缓存8小时

问题：“连接超时”

检查互联网连接
验证Cloud Run服务是否正在运行
测试： curl https://trello-mcp-116435607783.us-central1.run.app/health

问题：“找不到httpx”

安装： pip3 install httpx
验证： python3 -c "import httpx"

自定义AI代理集成

看 集成指南 以上部分为：

自定义AI代理的Python客户端示例
JavaScript/Node.js客户端示例
完整的实施模式

🏗️ 建筑

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Agent      │────│  Trello MCP      │────│   Trello API    │
│   (Claude)      │    │  Server          │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
        │                        │                        │
        │ MCP Protocol           │ HTTP/REST              │
        │ (JSON-RPC 2.0)         │                        │
        └────────────────────────┴────────────────────────┘
                              
Components:
• FastAPI HTTP Server (main.py)
• MCP Protocol Handler (mcp_server.py) 
• Trello API Client (trello_client.py)
• 11 Tools Implementation (tools.py)
• Security & Validation (schemas.py)

🔐 安全模型

凭证处理

从未储存：每个调用请求的API密钥
验证：在每次请求时验证凭据
隔离：每个请求都由用户凭据隔离
没有毅力：无状态服务器设计

输入验证

# All inputs validated with Pydantic
class CreateCardRequest(BaseModel):
    name: str = Field(..., max_length=16384)
    list_id: str = Field(..., min_length=1)
    desc: Optional[str] = Field(None, max_length=16384)
    
    @validator('name')
    def validate_name(cls, v):
        if not v.strip():
            raise ValueError("Card name cannot be empty")
        return v.strip()

速率限制

# Respects Trello's 300 requests per 10 seconds
class RateLimiter:
    def __init__(self, max_requests=300, time_window=10):
        # Implementation ensures compliance

📊 监测和可观察性

健康检查

GET /health
{
  "status": "healthy",
  "service": "trello-mcp", 
  "version": "1.0.0",
  "timestamp": "2024-01-01T00:00:00Z",
  "mcp_server": "initialized",
  "tools_count": 11
}

结构化日志记录

{
  "timestamp": "2024-01-01T00:00:00Z",
  "severity": "INFO",
  "message": "Tool execution completed: create_card",
  "logger": "trello_mcp",
  "service": "trello-mcp",
  "version": "v1.0.0"
}

错误处理

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Unauthorized - check your API key and token",
    "data": "Invalid API credentials provided"
  }
}

💰 成本细分

Google Cloud Run的每月费用：

组件	成本
云运行（2M免费请求）	自由
容器注册表	~0.40美元
云日志	~1.00美元
总计	~$1-2

成本因素：

免费套餐：每月200万次请求
免费套餐后每百万次请求0.40美元
最低的存储和日志记录成本

🚀 高级配置

环境变量

# Server configuration
DEBUG=false
LOG_LEVEL=INFO
REQUEST_TIMEOUT=30
MAX_RETRIES=3

# NEW: Optional pre-configured credentials (for non-interactive deployment)
# When set, these will be automatically loaded at startup
# Set BOTH for non-interactive mode, or neither for interactive login
TRELLO_USERNAME=your-api-key        # Trello API key
TRELLO_PASSWORD=your-api-token      # Trello API token

# Cloud Run auto-injected
K_SERVICE=trello-mcp
K_REVISION=trello-mcp-00001-abc
PORT=8080

有关详细的环境变量文档，请参阅 ENV_VARIABLES.md

使用预配置的凭据（云运行）：

gcloud run deploy trello-mcp \
  --source . \
  --region us-central1 \
  --set-env-vars="TRELLO_USERNAME=your-api-key,TRELLO_PASSWORD=your-api-token" \
  --allow-unauthenticated

使用云秘密（推荐）：

# Create secrets
gcloud secrets create trello-api-key --replication-policy="automatic" --data-file=- <<< "your-api-key"
gcloud secrets create trello-api-token --replication-policy="automatic" --data-file=- <<< "your-api-token"

# Deploy with secrets
gcloud run deploy trello-mcp \
  --source . \
  --region us-central1 \
  --set-env-vars="TRELLO_USERNAME=projects/PROJECT_ID/secrets/trello-api-key/versions/latest,TRELLO_PASSWORD=projects/PROJECT_ID/secrets/trello-api-token/versions/latest" \
  --allow-unauthenticated

自定义部署

# cloudbuild.yaml customization
steps:
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '--tag', 'gcr.io/$PROJECT_ID/trello-mcp:latest', '.']
    
  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
    args: [
      'run', 'deploy', 'trello-mcp',
      '--memory', '1Gi',           # Increase memory
      '--cpu', '2',                # Increase CPU
      '--concurrency', '100',      # Higher concurrency
      '--max-instances', '50'      # Scale limit
    ]

🧪 测试

地方发展

# Install dependencies
pip install -r requirements.txt

# Run locally
python main.py

# Test endpoints
curl http://localhost:8080/health
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

验证脚本

# test_imports.py - verify all components load
import sys
import asyncio

async def test_server():
    try:
        from main import app
        from tools import TrelloTools
        
        tools = TrelloTools()
        available_tools = tools.get_tools()
        
        print(f"✅ Server loaded successfully")
        print(f"✅ {len(available_tools)} tools registered")
        
        expected_tools = [
            "list_boards", "get_board", "create_board", "update_board",
            "get_lists", "create_list", "get_cards", "create_card", 
            "update_card", "add_member_to_card", "search_cards"
        ]
        
        for tool in expected_tools:
            if tool in available_tools:
                print(f"✅ {tool}")
            else:
                print(f"❌ {tool} missing")
                
    except Exception as e:
        print(f"❌ Error: {e}")
        sys.exit(1)

if __name__ == "__main__":
    asyncio.run(test_server())

🆘 故障排除

常见问题

“无法解决导入问题”

# Install dependencies
pip install -r requirements.txt

“未经授权-检查您的API密钥和令牌”

# Verify credentials at https://trello.com/app-key
# Ensure token is not expired
# Check API key format (32 characters)

“超出费率限制”

# Server automatically handles rate limiting
# Wait 10 seconds and retry
# Consider reducing request frequency

云运行时构建失败

# Check billing is enabled
gcloud billing accounts list

# Verify APIs are enabled  
gcloud services enable run.googleapis.com cloudbuild.googleapis.com

# Check quotas
gcloud compute project-info describe --project=$PROJECT_ID

调试模式

# Enable debug logging
export DEBUG=true
export LOG_LEVEL=DEBUG

python main.py

日志分析

# View Cloud Run logs
gcloud run logs read trello-mcp --region=us-central1 --limit=50

# Filter for errors
gcloud run logs read trello-mcp --region=us-central1 | grep ERROR

# Real-time logs
gcloud run logs tail trello-mcp --region=us-central1

🤝 贡献

开发环境设置

git clone <repository>
cd trello-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Run tests
python test_imports.py

代码风格

PEP 8 顺从的
键入提示 适用于所有功能
文档字符串 适用于所有模块和类
错误处理 除特定例外情况

📄 许可证

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

🙋‍♂️ 支持

文档：检查 QUICKSTART.md 和 FILE_MANIFEST.md
问题：为bug/功能创建GitHub问题
建筑：参见 DEPLOYMENT_SUMMARY.md

📚 相关文件

入门指南

START_HERE.txt -首次入职培训
QUICKSTART.md -5分钟部署指南
QUICK_START_LOGIN.txt - ⭐ 新增：2分钟交互式登录指南

交互式登录功能（新增！）

互动_LOGIN_GUIDE.md -带示例的完整指南
登录_功能.md -功能概述和优点
特色_苏玛丽.txt -可视化图表和实现细节

架构和部署

部署_ SUMMARY.md -建筑深度挖掘
实施_ SUMMARY.md -实施细节
FILE_MANIFEST.md -按文件细分

测试

测试指南.md -全面的测试指南

内置❤️ 实现Trello AI的无缝集成

使用说明

📋 Trello MCP服务器

🎯 这是什么

✨ 主要特点

🔐 交互式登录系统 新

🔒 安全第一

🚀 生产就绪

🛠️ 完整的工具集

📦 包含什么

🚀 快速开始

1.获取Trello证书

2.部署到云端运行

3.测试您的服务器

🛠️ 全部11个工具

📋 使用示例

MCP协议集成

创建新董事会

搜索紧急卡

创建和分配卡片

🔗 集成指南

⭐ Claude桌面集成

步骤1：下载代理服务器

步骤2：安装依赖项

步骤3：配置Claude桌面

步骤4:重新启动克劳德桌面

步骤5：验证连接

VS代码集成

配置文件

验证连接

光标集成

步骤1：获取代理服务器

步骤2：安装依赖项

步骤3：配置游标

步骤4：重新启动游标

Cline（VS代码扩展）集成

配置

与Cline一起使用

LM工作室集成

配置

Zed集成

配置

自定义AI集成

Python客户端示例

JavaScript/Node.js客户端示例

集成汇总表

开始使用每个工具

适用于克劳德桌面

用于VS代码/光标

用于自定义集成

故障排除集成

自定义AI代理集成

🏗️ 建筑

🔐 安全模型

凭证处理

输入验证

速率限制

📊 监测和可观察性

健康检查

结构化日志记录

错误处理

💰 成本细分

🚀 高级配置

环境变量

自定义部署

🧪 测试

地方发展

验证脚本

🆘 故障排除

常见问题

调试模式

日志分析

🤝 贡献

开发环境设置

代码风格

📄 许可证

🙋‍♂️ 支持

📚 相关文件

入门指南

交互式登录功能（新增！）

架构和部署

🔐 交互式登录系统新