SuhoPlan MCP Server

MCP (Model Context Protocol) server for integrating SuhoPlan shared boards with Claude Code. This allows Claude to naturally interact with your shared boards, issues, comments, and checklists.

Features

• 📋 Board Management: Automatically connected to your board via PAT token
• 🎯 Issue Operations: Create, read, update, and complete issues
• 💬 Comments: Add and view comments on issues
• ✅ Checklists: Manage checklist items within issues
• 👥 Team Collaboration: View board members and assignees
• 🔍 Filtering: Filter issues by status (TODO, IN_PROGRESS, DONE, etc.)
• 🔐 Token Management: Board owners can manage and revoke tokens
• 🔗 Git Integration (Optional): Connect GitHub or GitLab repositories

Installation

npm install -g suhoplan-mcp-server

또는 npx로 바로 사용 가능 (설치 불필요)

Quick Start (3 Steps)

1. Create PAT Token (앱에서)

앱의 공유보드 설정에서 PAT(Personal Access Token)을 생성합니다:

• 설정 → 토큰 관리 → 새 토큰 생성
• 토큰은 보드 하나에 연결됩니다
• 생성된 suho_... 토큰을 복사하세요

2. Claude Desktop 설정

설정 파일 위치:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/claude/config.json

{
  "mcpServers": {
    "suhoplan": {
      "command": "npx",
      "args": ["-y", "suhoplan-mcp-server"],
      "env": {
        "SUHOPLAN_API_URL": "https://api.suhoplan.com",
        "SUHOPLAN_AUTH_TOKEN": "suho_your_token_here"
      }
    }
  }
}

중요: SUHOPLAN_ACCOUNT_IDX는 더 이상 필요하지 않습니다! PAT 토큰에서 자동으로 사용자와 보드 정보를 가져옵니다.

3. Claude Desktop 재시작

설정 후 Claude Desktop을 완전히 종료하고 다시 시작합니다.

Git Integration (Optional)

GitHub 또는 GitLab 저장소를 연동하여 Claude가 브랜치, PR/MR, 커밋 등을 관리할 수 있습니다.

환경변수 설정

Claude Desktop 설정에 Git 관련 환경변수를 추가합니다:

{
  "mcpServers": {
    "suhoplan": {
      "command": "npx",
      "args": ["-y", "suhoplan-mcp-server"],
      "env": {
        "SUHOPLAN_API_URL": "https://api.suhoplan.com",
        "SUHOPLAN_AUTH_TOKEN": "suho_your_token_here",

        "GIT_TYPE": "GITHUB",
        "GIT_TOKEN": "ghp_your_github_token",
        "GIT_REPO_URL": "https://github.com/owner/repo"
      }
    }
  }
}

환경변수 설명

| 변수 | 필수 | 설명 | |------|------|------| | GIT_TYPE | 선택 | GITHUB 또는 GITLAB (기본: GITHUB) | | GIT_TOKEN | 필수 | GitHub PAT 또는 GitLab Access Token | | GIT_REPO_URL | 필수 | 저장소 URL (예: https://github.com/owner/repo) | | GIT_API_URL | 선택 | Self-hosted GitLab API URL (예: https://git.company.com/api/v4) |

GitHub 토큰 생성

1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate new token (classic)
3. 필요한 권한 선택:
   • repo - 저장소 접근
   • read:org - 조직 정보 (필요 시)
4. 토큰 복사 (ghp_...)

GitLab 토큰 생성

1. GitLab → User Settings → Access Tokens
2. 필요한 scopes 선택:
   • api - API 전체 접근
   • read_repository - 저장소 읽기
   • write_repository - 저장소 쓰기
3. 토큰 복사

Self-hosted GitLab 설정

{
  "env": {
    "GIT_TYPE": "GITLAB",
    "GIT_TOKEN": "glpat-your_gitlab_token",
    "GIT_REPO_URL": "https://git.company.com/group/project",
    "GIT_API_URL": "https://git.company.com/api/v4"
  }
}

보안 참고사항

• Git 토큰은 서버에 저장되지 않습니다
• 각 사용자가 자신의 MCP 설정에서 직접 관리합니다
• 토큰은 로컬 환경변수로만 사용됩니다

Available Tools

Once installed, Claude Code will have access to these tools:

• list_boards - Get all shared boards
• list_issues - Get issues from a specific board
• get_issue - Get detailed issue information
• create_issue - Create a new issue
• update_issue - Update an existing issue
• mark_issue_done - Mark an issue as completed
• delete_issue - Delete an issue
• get_comments - Get comments for an issue
• create_comment - Add a comment to an issue
• get_board_members - List board members
• get_checklist - Get checklist items for an issue
• create_checklist_item - Add a checklist item
• toggle_checklist_item - Check/uncheck a checklist item

Git Tools (Optional)

Git 연동 설정 시 추가되는 도구들:

• git_repo_info - Get repository information
• git_list_branches - List all branches
• git_create_branch - Create a new branch
• git_list_pull_requests - List PRs (GitHub) or MRs (GitLab)
• git_create_pull_request - Create a new PR/MR
• git_get_pull_request - Get PR/MR details
• git_list_commits - List recent commits
• git_list_issues - List repository issues

PAT Token Management

Creating a PAT Token (API)

If you need to create a token programmatically:

# 1. Login to get JWT token
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"accountId":"your_id","password":"your_password"}'

# 2. Create PAT token (boardId is required!)
curl -X POST http://localhost:8080/api/token/create \
  -H "Content-Type: application/json" \
  -H "authToken: YOUR_JWT_TOKEN" \
  -d '{
    "name": "Claude MCP",
    "description": "Token for Claude Code integration",
    "boardId": 123,
    "expiresInDays": null
  }'

Token Revocation (Board Owner/Admin)

Board owners and admins can view and revoke tokens:

# List all tokens for a board
curl -X POST http://localhost:8080/api/board/token/list \
  -H "Content-Type: application/json" \
  -H "authToken: YOUR_JWT_TOKEN" \
  -d '{"boardId": 123}'

# Revoke a token
curl -X POST http://localhost:8080/api/board/token/revoke \
  -H "Content-Type: application/json" \
  -H "authToken: YOUR_JWT_TOKEN" \
  -d '{"boardId": 123, "tokenId": 456}'

Usage Examples

Once configured, interact with SuhoPlan naturally through Claude:

View issues

Show me all TODO issues

Create an issue

Create a new issue:
Title: "Fix authentication bug"
Description: "Users can't log in with email"
Priority: High

Update issue status

Mark issue 456 as done

Add a comment

Add a comment to issue 456: "This has been fixed in the latest deploy"

Git Integration Examples

Show me the recent commits

Create a new branch called "feature/issue-123-login-fix" from main

List all open pull requests

Create a PR for the feature/login-fix branch

How It Works

┌─────────────────┐     PAT Token      ┌─────────────────┐
│  Claude Code    │ ───────────────────▶│  SuhoPlan API   │
│  (MCP Server)   │                     │                 │
└─────────────────┘                     └─────────────────┘
        │                                       │
        │ 1. /api/board/me                     │
        │    → accountIdx, boardId 자동 조회    │
        │                                       │
        │ 2. API 호출 시 자동으로              │
        │    accountIdx 포함                   │
        ▼                                       ▼
┌─────────────────────────────────────────────────────────┐
│  PAT Token = 사용자 + 보드 정보 포함                    │
│  → accountIdx 설정 불필요!                              │
│  → 보드 자동 연결!                                      │
└─────────────────────────────────────────────────────────┘

Development

Running from source

# Install dependencies
cd suhoplan-mcp-server
npm install

# Create .env file
cp .env.example .env

# Edit with your PAT token
nano .env

# Test
npm start

Project Structure

suhoplan-mcp-server/
├── src/
│   ├── index.js       # MCP server entry point
│   ├── api-client.js  # SuhoPlan API client
│   ├── git-client.js  # GitHub/GitLab API client
│   └── tools.js       # MCP tool definitions
├── package.json
├── .env.example
└── README.md

Troubleshooting

"Failed to initialize" 에러

1. PAT 토큰이 유효한지 확인
2. 서버가 실행 중인지 확인
3. API URL이 올바른지 확인 (http:// 또는 https:// 포함)

Permission denied 에러

• PAT 토큰이 해당 보드에 접근 권한이 있는지 확인
• 토큰이 만료되었거나 revoke 되었는지 확인

연결이 안 될 때

1. Claude Desktop 로그 확인
2. 서버가 실행 중인지 확인
3. 방화벽 설정 확인

API Endpoints

MCP 서버가 사용하는 API 엔드포인트:

| Endpoint | Description | |----------|-------------| | POST /api/board/me | PAT 토큰으로 사용자/보드 정보 조회 | | POST /api/board/issue/list | 이슈 목록 조회 | | POST /api/board/issue/create | 이슈 생성 | | POST /api/board/issue/update | 이슈 수정 | | POST /api/board/token/list | 보드 토큰 목록 (오너/관리자) | | POST /api/board/token/revoke | 토큰 강제 만료 (오너/관리자) |

License

MIT