Trello MCP 서버

🔀 활성 포크. 이 프로젝트는 kocakli/Trello-Desktop-MCP의 유지 관리되는 포크이며, 포크 생태계 전반의 기여(kevinhillinger, zonca, dbz-max, maks244, jantman, ThatIanMcShane, josh-argyle)를 통합했습니다. PR은 언제나 환영합니다. 각 기여자가 제공한 내용은 Credits를 참조하세요. npm에 atlassian-trello-mcp로 게시되었습니다.

Claude Desktop, Claude Code, Gemini CLI 등 모든 MCP 호환 클라이언트와 함께 작동하는 Trello용 MCP(Model Context Protocol) 서버입니다.

보드, 카드, 리스트, 라벨, 체크리스트, 첨부 파일, 멤버, 사용자 지정 필드 및 검색을 아우르는 46개의 도구를 제공합니다.

빠른 시작

1. Trello API 자격 증명 가져오기

• https://trello.com/app-key 방문

• API Key 복사

• 읽기/쓰기 권한을 위해 "Generate a Token" 클릭

2. 설치

가장 쉬운 방법은 npx를 사용하는 것입니다. 복제나 빌드 없이 바로 실행할 수 있습니다:

npx atlassian-trello-mcp

또는 소스에서 설치:

git clone https://github.com/agrath/Trello-Desktop-MCP.git
cd Trello-Desktop-MCP
npm install
npm run build

3. MCP 클라이언트 구성

설정 파일을 편집하세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "atlassian-trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your-api-key",
        "TRELLO_TOKEN": "your-token"
      }
    }
  }
}

claude mcp add trello -- npx -y atlassian-trello-mcp

환경 변수 TRELLO_API_KEY 및 TRELLO_TOKEN을 설정하거나 요청별로 자격 증명을 전달하세요.

~/.gemini/settings.json 편집:

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["-y", "atlassian-trello-mcp"],
      "env": {
        "TRELLO_API_KEY": "your-api-key",
        "TRELLO_TOKEN": "your-token"
      }
    }
  }
}

이 서버는 stdio 전송을 사용합니다. 환경 변수를 설정하고 실행하세요:

TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token npx atlassian-trello-mcp
# or, from a source clone:
TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token node dist/index.js

Related MCP server: fastmcp-trello

자격 증명

자격 증명은 두 가지 방법으로 제공할 수 있습니다:

1. 환경 변수 (권장): TRELLO_API_KEY 및 TRELLO_TOKEN 설정

2. 요청별: 도구 매개변수로 apiKey 및 token 전달 (환경 변수보다 우선)

사용 가능한 도구 (46개)

보드 및 리스트

카드

댓글 및 활동

라벨

카드 멤버

첨부 파일

체크리스트

체크 항목

검색

구성

읽기 전용 모드

TRELLO_READ_ONLY=true를 설정하여 모든 쓰기 작업을 비활성화합니다. 읽기/쿼리 도구만 사용할 수 있습니다.

{
  "env": {
    "TRELLO_API_KEY": "your-key",
    "TRELLO_TOKEN": "your-token",
    "TRELLO_READ_ONLY": "true"
  }
}

압축 모드

여러 도구가 응답 크기를 줄이기 위해 최소한의 필드만 반환하는 compact 매개변수(기본값: true)를 지원합니다. 설명, 라벨, 멤버, 사용자 지정 필드를 포함한 전체 세부 정보를 보려면 compact: false로 설정하세요.

압축 모드를 지원하는 도구: get_board_details, trello_get_board_cards, trello_get_list_cards, trello_search.

이미지 첨부 파일 다운로드

get_card 호출 시 카드에 이미지 첨부 파일이 있으면 서버가 이를 다운로드하여 JSON과 함께 인라인 MCP 이미지 콘텐츠 블록으로 반환하므로 클라이언트가 카드 이미지를 직접 볼 수 있습니다. 다운로드는 Trello 호스팅 URL(*.trello.com, trello-attachments.s3.amazonaws.com)으로 제한되며, SSRF 및 페이로드 비대화 위험을 완화하기 위해 이미지당 5MB로 제한됩니다.

TRELLO_DOWNLOAD_IMAGES=false(또는 0/no/off)를 설정하여 완전히 비활성화할 수 있습니다. 이 경우 서버는 추가 getCardAttachments 호출을 건너뛰고 텍스트만 반환합니다. 기본값은 활성화입니다.

로깅

TRELLO_MCP_LOGGING=true를 설정하여 Pino를 통한 파일 기반 로깅을 활성화합니다. 로그는 dist/logs/app.log에 기록됩니다.

개발

프로젝트 구조

src/
  index.ts              Entry point (credential injection, tool routing)
  server.ts             MCP server factory (read-only mode support)
  tools/
    boards.ts           Board tools (list, details, lists, filter)
    cards.ts            Card tools (CRUD, archive)
    lists.ts            List tools (cards, create list, comments)
    members.ts          Member tools (user boards, member details)
    search.ts           Search tool
    advanced.ts         Labels, attachments, members on cards, custom fields
    checklists.ts       Checklist and check item tools (13 tools)
  trello/
    client.ts           TrelloClient (API calls, retry, rate limiting)
  types/
    trello.ts           TypeScript interfaces
  utils/
    validation.ts       Zod schemas, extractCredentials, extractTrelloId
    logger.ts           Pino file logger
    health.ts           Health check utility
    appInsights.ts      Telemetry (no-op)
tests/
  validation.test.ts    Validation and credential extraction tests
  trelloClient.test.ts  API client tests (mocked fetch)
  tools.test.ts         Tool handler tests (mocked client)

빌드 및 테스트

npm install
npm run build
npm test
npm run type-check

주요 패턴

• ID 확인: 모든 도구는 extractTrelloId()를 통해 Trello URL, 짧은 ID 또는 전체 24자 16진수 ID를 허용합니다.

• 자격 증명 폴백: extractCredentials()는 먼저 인수를 확인한 다음 환경 변수를 확인합니다.

• 지수 백오프 재시도: TrelloClient는 500/네트워크 오류 발생 시 재시도합니다 (3회 시도, 지수 백오프).

• 속도 제한: 모든 응답에서 x-rate-limit-* 헤더를 추출하여 반환합니다.

• 유효성 검사: Zod 스키마가 API 호출 전 모든 입력을 검증합니다.

기여

풀 리퀘스트는 언제나 환영하며 적극적으로 검토됩니다. 이 포크는 숙련된 Trello 사용자가 유지 관리하므로 기능들이 실제 환경에서 테스트됩니다.

원본 프로젝트를 포크하여 유용한 기능을 만드셨다면, 별도의 포크를 유지하는 대신 여기에 PR을 제출해 주세요. 잘 관리되는 단일 프로젝트를 통해 모두가 혜택을 받는 것이 더 좋습니다.

기여 방법:

1. 이 저장소 포크

2. 기능 브랜치 생성

3. 새로운 기능에 대한 테스트 추가

4. npm test 및 npm run build 실행

5. 무엇을, 왜 변경했는지 명확하게 설명하여 풀 리퀘스트 제출

크레딧

이 프로젝트는 kocakli/Trello-Desktop-MCP의 포크입니다. 포크 생태계 전반의 기능과 아이디어가 통합되었습니다:

• kocakli -- 원본 프로젝트, MCP 클라이언트 독립적 리브랜딩, stderr 로깅 수정

• kevinhillinger -- 자격 증명 주입 아키텍처, 라벨 삭제, 카드 멤버 관리, 카드 보관, 확장된 TypeScript 타입, 리소스 계층

• zonca -- 환경 변수 폴백을 포함한 중앙 집중식 자격 증명 처리, 라벨 관리 도구, 포괄적인 단위 테스트, any를 대체하는 개선된 TypeScript 타입

• dbz-max -- 사용자 지정 필드 지원 (보드 사용자 지정 필드 + 카드 사용자 지정 필드 항목)

• maks244 -- 읽기 전용 모드 개념, 이름별 리스트 필터링, 원격 측정 로그에서 자격 증명 제거

• jantman -- MCP 클라이언트가 문자열로 보낼 때 거부되는 숫자 pos 값 수정

• ThatIanMcShane -- @modelcontextprotocol/sdk 1.0.4 → 1.29.0으로 업데이트하여 현재 Claude Code 릴리스와의 연결 시간 초과 문제 해결

• josh-argyle -- get_card 응답에서 이미지 첨부 파일을 인라인 MCP 이미지 콘텐츠 블록으로 자동 다운로드 (포팅 중 허용 목록 + 크기 제한 추가)

라이선스

MIT