clickup-multi-mcp-server: Instructions file for Claude Code

ClickUp Multi-Workspace MCP Server — Developer Guide

Project Overview

A Model Context Protocol (MCP) server that exposes ClickUp API operations as tools for AI agents. Supports multiple ClickUp workspaces simultaneously via a unified interface.

File Architecture

src/
├── index.ts                        # Entry point — starts STDIO/HTTP transports
├── server.ts                       # MCP server: registers all tools + routes CallTool requests
├── config.ts                       # Reads env vars (API keys, feature flags, tool filters)
├── logger.ts                       # Structured logger used throughout the codebase
│
├── services/
│   ├── shared.ts                   # Singleton: exports instantiated services for default workspace
│   └── clickup/
│       ├── index.ts                # Factory function createClickUpServices() + ClickUpServices type
│       ├── base.ts                 # BaseClickUpService: Axios client, makeRequest(), logOperation()
│       ├── types.ts                # All shared TypeScript types and interfaces for ClickUp API
│       ├── workspace.ts            # WorkspaceService — hierarchy, members
│       ├── task/
│       │   ├── index.ts            # Re-exports all task service methods
│       │   ├── task-core.ts        # TaskServiceCore — base task CRUD
│       │   ├── handlers.ts         # High-level task handlers (smart lookup by name)
│       │   └── workspace-operations.ts  # Bulk task operations
│       ├── list.ts                 # ListService — list CRUD
│       ├── folder.ts               # FolderService — folder CRUD
│       ├── space.ts                # SpaceService — space CRUD
│       ├── tag.ts                  # TagService — space tags and task tags
│       ├── member.ts               # MemberService — member lookup and assignee resolution
│       ├── time.ts                 # TimeTrackingService — start/stop/entries
│       ├── document.ts             # DocumentService — docs and pages
│       ├── goal.ts                 # GoalService — goals and key results
│       ├── checklist.ts            # ChecklistService — task checklists and items
│       └── view.ts                 # ViewService — views across all hierarchy levels
│
├── tools/
│   ├── index.ts                    # Re-exports from all tool modules (subset; server.ts imports directly)
│   ├── workspace.ts                # Tools: get_workspace_hierarchy, get_available_workspaces
│   ├── task/
│   │   ├── index.ts                # Re-exports all task tool definitions and handlers
│   │   ├── definitions.ts          # Tool schema definitions for task operations
│   │   └── handlers.ts             # Tool handler functions for task operations
│   ├── list.ts                     # Tools: create_list, get_list, update_list, delete_list, create_list_in_folder
│   ├── folder.ts                   # Tools: create_folder, get_folder, update_folder, delete_folder
│   ├── space.ts                    # Tools: get_spaces, get_space, create_space, update_space, delete_space
│   ├── tag.ts                      # Tools: get_space_tags, add_tag_to_task, remove_tag_from_task
│   ├── member.ts                   # Tools: get_workspace_members, find_member_by_name, resolve_assignees
│   ├── documents.ts                # Tools: create_document, get_document, list_documents, etc.
│   ├── goal.ts                     # Tools: get_goals, create_goal, update_goal, delete_goal, key results
│   ├── dependency.ts               # Tools: add_dependency, delete_dependency, add_task_link, delete_task_link
│   ├── checklist.ts                # Tools: create_checklist, edit_checklist, delete_checklist, items
│   ├── view.ts                     # Tools: get/create views (workspace/space/folder/list), update/delete view, get_view_tasks
│   ├── tool-enhancer.ts            # Injects workspace parameter into every tool schema
│   └── workspace-helper.ts        # getServicesForWorkspace() — resolves correct service set from params
│
└── utils/
    └── sponsor-service.ts          # createResponse() / createErrorResponse() — standard MCP response format