[](https://github.com/s.pawel940/clickup-mcp-server/stargazers) [](https://github.com/s.pawel940/clickup-mcp-server/graphs/commit-activity) A Model Context Protocol (MCP) server for integrating ClickUp tasks with AI applications. This server allows AI agents to interact with ClickUp tasks, spaces, lists, and folders through a standardized protocol. The server operates in read-only mode, providing safe and secure access to view and analyze ClickUp data without the risk of modifications. This is a fork of the original [clickup-mcp-server](https://github.com/TaazKareem/clickup-mcp-server) repository, modified to operate in read-only mode for enhanced security and data protection. ## Setup 1. Get your credentials: - ClickUp API key from [ClickUp Settings](https://app.clickup.com/settings/apps) - Team ID from your ClickUp workspace URL 2. Choose either hosted installation (sends webhooks) or NPX installation (downloads to local path and installs dependencies) 3. Use natural language to manage your workspace! ## Smithery Installation (Quick Start) [](https://smithery.ai/server/@TaazKareem/clickup-mcp-server) The server is hosted on [Smithery](https://smithery.ai/server/@taazkareem/clickup-mcp-server). There, you can preview the available tools or copy the commands to run on your specific client app. ## NPX Installation [](https://www.npmjs.com/package/@s.pawel940/clickup-mcp-server) [](https://github.com/s.pawel940/clickup-mcp-server/blob/main/package.json) [](https://npmcharts.com/compare/@s.pawel940/clickup-mcp-server?minimal=true) Add this entry to your client's MCP settings JSON file: ```json { "mcpServers": { "ClickUp": { "command": "npx", "args": [ "-y", "@s.pawel940/clickup-mcp-server@latest" ], "env": { "CLICKUP_API_KEY": "your-api-key", "CLICKUP_TEAM_ID": "your-team-id", "DOCUMENT_SUPPORT": "true" } } } } ``` Or use this npx command: `npx -y @s.pawel940/clickup-mcp-server@latest --env CLICKUP_API_KEY=your-api-key --env CLICKUP_TEAM_ID=your-team-id` **Obs: if you don't pass "DOCUMENT_SUPPORT": "true", the default is false and document support will not be active.** Additionally, you can use the `DISABLED_TOOLS` environment variable or `--env DISABLED_TOOLS` argument to disable specific tools. Provide a comma-separated list of tool names to disable (e.g., `create_task,delete_task`). Please disable tools you don't need if you are having issues with the number of tools or any context limitations ## Running with SSE Support Server can be run in SSE (Server-Sent Events) mode by setting the following environment variables: ```json { "mcpServers": { "ClickUp": { "command": "npx", "args": [ "-y", "@s.pawel940/clickup-mcp-server@latest" ], "env": { "CLICKUP_API_KEY": "your-api-key", "CLICKUP_TEAM_ID": "your-team-id", "ENABLE_SSE": "true", "PORT": "8000" // Optional, defaults to 3231 } } } } ``` Or via command line: `npx -y @s.pawel940/clickup-mcp-server@latest --env CLICKUP_API_KEY=your-api-key --env CLICKUP_TEAM_ID=your-team-id --env ENABLE_SSE=true --env PORT=8000` ## Docker-compose example ```yaml version: '3.8' services: clickup-mcp-server: build: context: . dockerfile: Dockerfile ports: - '3231:8000' environment: - CLICKUP_API_KEY=${CLICKUP_API_KEY} - CLICKUP_TEAM_ID=${CLICKUP_TEAM_ID} - ENABLE_SSE=true - LOG_LEVEL=info - DOCUMENT_SUPPORT=true volumes: - ./src:/app/src restart: unless-stopped healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/health"] interval: 30s timeout: 10s retries: 3 start_period: 5s ``` ## Features | 📝 Task Management | 🏷️ Tag Management | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | • View and analyze tasks
• Get task details and relationships
• Support for single and bulk operations
• View start/due dates
• View subtasks
• Read comments and attachments | • View space tags
• View task tags
• Use natural language color commands
• Automatic contrasting foreground colors
• View all space tags
• Tag-based task organization across workspace | | ⏱️ **Time Tracking** | 🌳 **Workspace Organization** | | • View time entries for tasks
• View currently running timer
• Track billable and non-billable time | • Navigate spaces, folders, and lists
• View folder details
• View list details
• View workspace hierarchy
• Efficient path navigation | | 📄 **Document Management** | 👥 **Member Management** | | • Document Listing through all workspace
• Document Page listing
• Document Page Details | • Find workspace members by name or email
• View member details and permissions
• Support for user IDs, emails, or usernames
• Team-wide user management | | ⚡ **Integration Features** | | | • Global name or ID-based lookups
• Case-insensitive matching
• Markdown formatting support
• Built-in rate limiting
• Error handling and validation
• Comprehensive API coverage | | ## Available Tools | Tool | Description | Required Parameters | | ------------------------------------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | [get_workspace_hierarchy](docs/api-reference.md#workspace-navigation) | Get workspace structure | None | | [get_tasks](docs/api-reference.md#task-management) | Get tasks from list | `listId`/`listName` | | [get_task](docs/api-reference.md#task-management) | Get single task details | `taskId`/`taskName` (with smart disambiguation) | | [get_workspace_tasks](docs/api-reference.md#task-management) | Get tasks with filtering | At least one filter (tags, list_ids, space_ids, etc.) | | [get_task_comments](docs/api-reference.md#task-management) | Get comments on a task | `taskId`/`taskName` | | [get_folder](docs/api-reference.md#folder-management) | Get folder details | `folderId`/`folderName` | | [get_list](docs/api-reference.md#list-management) | Get list details | `listId`/`listName` | | [get_space_tags](docs/api-reference.md#tag-management) | Get space tags | `spaceId`/`spaceName` | | [get_task_time_entries](docs/api-reference.md#time-tracking) | Get time entries for a task | `taskId`/`taskName` | | [get_current_time_entry](docs/api-reference.md#time-tracking) | Get currently running timer | None | | [get_workspace_members](docs/api-reference.md#member-management) | Get all workspace members | None | | [find_member_by_name](docs/api-reference.md#member-management) | Find member by name or email | `nameOrEmail` | | [get_document](docs/api-reference.md#document-management) | Get a document | `workspaceId`/`documentId` | | [list_documents](docs/api-reference.md#document-management) | List documents | `workspaceId`, `documentId`/`creator`/`deleted`/`archived`/`parent_id`/`parent_type`/`limit`/`next_cursor` | | [list_document_pages](docs/api-reference.md#document-management) | List document pages | `documentId`/`documentName` | | [get_document_pages](docs/api-reference.md#document-management) | Get document pages | `documentId`/`documentName`, `pageIds` | See [full documentation](docs/api-reference.md) for optional parameters and advanced usage. ## Member Management Tools The server provides read-only access to member information, allowing you to view and search for workspace members: ```json { "name": "View Task", "description": "This is an existing task.", "assignees": ["jdoe@example.com", "Jane Smith"] // For viewing assignee information only } ``` The member management tools help identify and view user information when needed. ## Prompts Not yet implemented and not supported by all client apps. Request a feature for a Prompt implementation that would be most beneficial for your workflow (without it being too specific). Examples: | Prompt | Purpose | Features | | -------------------------------------------------- | ------------------------- | ----------------------------------------- | | [summarize_tasks](docs/api-reference.md#prompts) | Task overview | Status summary, priorities, relationships | | [analyze_priorities](docs/api-reference.md#prompts) | Priority analysis | Distribution analysis, sequencing | | [generate_description](docs/api-reference.md#prompts) | Task description analysis | Objectives, criteria, dependencies | ## Error Handling The server provides clear error messages for: - Missing required parameters - Invalid IDs or names - Items not found - Permission issues - API errors - Rate limiting The `LOG_LEVEL` environment variable can be specified to control the verbosity of server logs. Valid values are `trace`, `debug`, `info`, `warn`, and `error` (default). This can be also be specified on the command line as, e.g. `--env LOG_LEVEL=info`. ## Support the Developer This is a fork of the original project by [TaazKareem](https://github.com/TaazKareem/clickup-mcp-server). If you find this project useful, please consider supporting the original author: [](https://github.com/sponsors/TaazKareem) ## Acknowledgements Special thanks to: - [ClickUp](https://clickup.com) for their excellent API and services that make this integration possible - [TaazKareem](https://github.com/TaazKareem) for creating the original project ## Contributing Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details. ## License [](https://opensource.org/licenses/MIT) This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Disclaimer This software makes use of third-party APIs and may reference trademarks or brands owned by third parties. The use of such APIs or references does not imply any affiliation with or endorsement by the respective companies. All trademarks and brand names are the property of their respective owners. This project is an independent work and is not officially associated with or sponsored by any third-party company mentioned.