{"_id":"@csevero/clickup-mcp","_rev":"2-0a8ea83286bfb01283a4f5c62dab02d2","name":"@csevero/clickup-mcp","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@csevero/clickup-mcp","version":"1.0.0","keywords":["mcp","clickup","model-context-protocol","ai"],"author":{"name":"Carlos Severo"},"license":"ISC","_id":"@csevero/clickup-mcp@1.0.0","maintainers":[{"name":"csevero","email":"severo.e.carlos@gmail.com"}],"homepage":"https://github.com/csevero/mcp-servers/tree/main/clickup","bugs":{"url":"https://github.com/csevero/mcp-servers/issues"},"bin":{"mcp-clickup":"build/index.js"},"dist":{"shasum":"158ce27b2d4f799738bf9ffc178af8b25583c880","tarball":"https://registry.npmjs.org/@csevero/clickup-mcp/-/clickup-mcp-1.0.0.tgz","fileCount":46,"integrity":"sha512-FetWO2Lf0WTBjluoWPePG6X767OdZVAsEX060fwKze/2v013SHXNKWC+3bTEr6da/8EcLK7Pl+CbGl65YBV62w==","signatures":[{"sig":"MEUCIDEmW3J6wZtNqldnMKBLau71pStFJJaNxHGheHARAEftAiEAyXFialvlD4a5ECkBMVyk/h01kdAQ7l2n8TlLBlpAbbY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42461},"main":"build/index.js","type":"module","types":"./build/index.d.ts","gitHead":"8ce27d52708d1966fb0142304c470813aa5b0356","scripts":{"dev":"npm run build && npm run start","build":"tsc && chmod +x build/index.js","start":"node build/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"csevero","email":"severo.e.carlos@gmail.com"},"repository":{"url":"git+https://github.com/csevero/mcp-servers.git","type":"git","directory":"clickup"},"_npmVersion":"10.5.2","description":"ClickUp MCP Server - Access ClickUp tasks via Model Context Protocol","directories":{},"_nodeVersion":"20.13.0","dependencies":{"zod":"^3.25.76","axios":"^1.11.0","dotenv":"^17.2.3","@modelcontextprotocol/sdk":"^1.17.5"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.2","@types/node":"^24.3.1"},"_npmOperationalInternal":{"tmp":"tmp/clickup-mcp_1.0.0_1759798346570_0.4865331630131138","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@csevero/clickup-mcp","version":"1.1.0","description":"ClickUp MCP Server - Access ClickUp tasks via Model Context Protocol","main":"build/index.js","type":"module","bin":{"mcp-clickup":"build/index.js"},"scripts":{"build":"tsc && chmod +x build/index.js","prepublishOnly":"npm run build","start":"node build/index.js","dev":"npm run build && npm run start"},"keywords":["mcp","clickup","model-context-protocol","ai"],"author":{"name":"Carlos Severo"},"license":"ISC","repository":{"type":"git","url":"git+https://github.com/csevero/mcp-servers.git","directory":"clickup"},"homepage":"https://github.com/csevero/mcp-servers/tree/main/clickup","bugs":{"url":"https://github.com/csevero/mcp-servers/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^1.17.5","axios":"^1.11.0","dotenv":"^17.2.3","zod":"^3.25.76"},"devDependencies":{"@types/node":"^24.3.1","typescript":"^5.9.2"},"_id":"@csevero/clickup-mcp@1.1.0","gitHead":"bf587fff0731f253c767d41921ab638c6994f2e9","types":"./build/index.d.ts","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-qUBWhga2D66yhRmTTPsQS8ZJnTqz0F3oGGgrzHvbfSVi1u+srBO5WwWnvKYG9tTMvdq0Ylhua5VoFWXxxRvi9A==","shasum":"e02cd8e46290184d4edff99f28d9858ed2687ff4","tarball":"https://registry.npmjs.org/@csevero/clickup-mcp/-/clickup-mcp-1.1.0.tgz","fileCount":54,"unpackedSize":59031,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDMRDc+Eagi6bPmy0Yit6/DDNpp3HYkYp0VqiGHI/9bKQIgITbBcXoEyk2xKmVyAOksRbENVjVJ8wLUUwHwfIdlMmo="}]},"_npmUser":{"name":"csevero","email":"severo.e.carlos@gmail.com"},"directories":{},"maintainers":[{"name":"csevero","email":"severo.e.carlos@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/clickup-mcp_1.1.0_1760835756529_0.8037371891627847"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-07T00:52:26.519Z","modified":"2025-10-19T01:02:36.925Z","1.0.0":"2025-10-07T00:52:26.744Z","1.1.0":"2025-10-19T01:02:36.727Z"},"bugs":{"url":"https://github.com/csevero/mcp-servers/issues"},"author":{"name":"Carlos Severo"},"license":"ISC","homepage":"https://github.com/csevero/mcp-servers/tree/main/clickup","keywords":["mcp","clickup","model-context-protocol","ai"],"repository":{"type":"git","url":"git+https://github.com/csevero/mcp-servers.git","directory":"clickup"},"description":"ClickUp MCP Server - Access ClickUp tasks via Model Context Protocol","maintainers":[{"name":"csevero","email":"severo.e.carlos@gmail.com"}],"readme":"# ClickUp MCP Server\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants to interact with ClickUp tasks and projects.\n\n## 🎯 What it does\n\nThis MCP server allows AI assistants like Claude to:\n\n- **Retrieve tasks** by Custom ID (e.g., EXP-1234)\n- **View task details** including name, description, status, attachments, and custom fields\n- **Get task comments** with formatted output for easy reading\n- **Access custom field details** for specific lists and fields\n- **Access ClickUp data** securely through your API credentials\n\n### 🚀 Coming Soon\n\nFuture versions will support:\n\n- **Task commenting** - Add progress updates and notes\n- **Status management** - Move tasks through workflow stages\n- **Task creation** - Generate new tasks from conversations\n- **Assignee management** - Distribute work across team members\n- **Bulk operations** - Handle multiple tasks efficiently\n- **Advanced filtering** - Search tasks by status, assignee, or date ranges\n\n## 🚀 Installation & Usage\n\n### Quick Start\n\nUsing Claude Code with the `mcp add` command (recommended):\n\n```bash\nclaude mcp add clickup --env CLICKUP_API_KEY=your_api_key_here \\\n  --env CLICKUP_TEAM_ID=your_team_id_here \\\n  -- npx @csevero/mcp-clickup\n```\n\n### Configuration\n\nBefore using the server, you need to set up your ClickUp API credentials:\n\n1. **Get your ClickUp API Key**:\n\n   - Go to ClickUp Settings → Apps\n   - Generate a new API token\n\n2. **Find your Team ID**:\n\n   - Go to your ClickUp workspace\n   - The Team ID is in the URL: `https://app.clickup.com/{TEAM_ID}/`\n\n3. **Set environment variables**:\n\n```bash\n# Create a .env file or set environment variables\nexport CLICKUP_API_KEY=\"your_api_key_here\"\nexport CLICKUP_TEAM_ID=\"your_team_id_here\"\n```\n\n### Claude Desktop Integration\n\n#### Option 1: Claude Code `mcp add` Command (Easiest)\n\nIf you're using Claude Code, simply run:\n\n```bash\nclaude mcp add clickup --env CLICKUP_API_KEY=your_api_key_here \\\n  --env CLICKUP_TEAM_ID=your_team_id_here \\\n  -- npx @csevero/mcp-clickup\n```\n\nThis automatically configures the MCP server for you.\n\n#### Option 2: Manual Configuration\n\nAdd this to your Claude Desktop configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"clickup\": {\n      \"command\": \"npx\",\n      \"args\": [\"@csevero/mcp-clickup\"],\n      \"env\": {\n        \"CLICKUP_API_KEY\": \"your_api_key_here\",\n        \"CLICKUP_TEAM_ID\": \"your_team_id_here\"\n      }\n    }\n  }\n}\n```\n\n#### Alternative: Command Line Arguments\n\nYou can also pass configuration via command line arguments:\n\n```json\n{\n  \"mcpServers\": {\n    \"clickup\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@csevero/mcp-clickup\",\n        \"--api-key\",\n        \"your_api_key_here\",\n        \"--team-id\",\n        \"your_team_id_here\"\n      ]\n    }\n  }\n}\n```\n\n#### Local Development Configuration\n\nFor local development, use the built version:\n\n```json\n{\n  \"mcpServers\": {\n    \"clickup\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/path/to/your/clickup/build/index.js\",\n        \"--api-key\",\n        \"your_api_key_here\",\n        \"--team-id\",\n        \"your_team_id_here\"\n      ]\n    }\n  }\n}\n```\n\n## 📖 Usage Examples\n\n### Basic Task Retrieval\n\n```\nAsk Claude: \"Get me the details for task EXP-1234\"\n```\n\nClaude will use the ClickUp MCP server to fetch and display:\n\n- Custom ID\n- Task name\n- Description\n- Status and priority\n- Assignees and watchers\n- Custom fields\n- Attachments\n\n### Task Comments Retrieval\n\n```\nAsk Claude: \"Show me all comments for task EXP-1234\"\n```\n\nClaude will retrieve and format all task comments with:\n\n- Comment author and timestamp\n- Formatted comment text\n- Reply counts\n- Support for rich content (images, links, mentions)\n\n### Custom Field Details\n\n```\nAsk Claude: \"Is the field 'custom' filled on task EXP-123?\"\n```\n\nClaude will first get the task details to retrieve the custom fields and list ID, then return the complete custom field configuration including:\n\n- Field name and type\n- Current value\n- Configuration options\n- Validation rules\n- Default values\n\n### Example Response\n\n```\nCustom ID: EXP-1234\nName: Implement user authentication\nDescription: Add OAuth2 login with Google and GitHub providers\nStatus: In Progress\nAssignees: john.doe@company.com\nAttachments: []\nCustom Fields: Priority: High, Sprint: Sprint 23\n```\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Node.js 18+\n- TypeScript\n- ClickUp API access\n\n### Local Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/csevero/mcp-servers\ncd mcp-servers/clickup\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run locally\nnode build/index.js\n```\n\n### Project Structure\n\n```\nclickup/\n├── src/\n│   ├── config/             # Configuration management\n│   │   ├── cli-parser.ts   # Command line argument parsing\n│   │   └── app-config.ts   # Configuration validation and loading\n│   ├── server/             # MCP server setup\n│   │   ├── mcp-server.ts   # Server creation and tool registration\n│   │   └── transport.ts    # Transport layer management\n│   ├── domain/             # Business entities and interfaces\n│   │   └── clickup.ts      # ClickUp repository interface\n│   ├── use-cases/          # Business logic\n│   │   ├── get-task.ts     # Get task use case\n│   │   ├── get-task-comments.ts # Get task comments use case\n│   │   ├── get-task-custom-field-detail.ts # Get custom field details\n│   │   └── index.ts        # Use cases exports\n│   ├── infra/              # Infrastructure layer\n│   │   └── clickup-repository.ts # ClickUp API implementation\n│   ├── types/              # Type definitions\n│   │   ├── api-responses.ts # ClickUp API response types\n│   │   └── entities.ts     # Core entity definitions\n│   └── index.ts            # Application entry point\n├── package.json\n└── README.md\n```\n\n### Architecture\n\nThis project follows **Clean Architecture** principles with **separated responsibilities**:\n\n- **Configuration Layer** (`src/config/`): CLI parsing, validation, and configuration management\n- **Server Layer** (`src/server/`): MCP server setup, tool registration, and transport management\n- **Domain Layer** (`src/domain/`): Core business logic and entities\n- **Use Cases** (`src/use-cases/`): Application-specific business rules\n- **Infrastructure** (`src/infra/`): External concerns (ClickUp API, HTTP client)\n- **Types** (`src/types/`): Type definitions and interfaces\n- **Entry Point** (`src/index.ts`): Minimal orchestration of all layers\n\n### Extensibility Design\n\nThe architecture is designed for easy extension with new ClickUp API features:\n\n#### 🔧 Adding New Tools\n\n1. **Repository Pattern**: All ClickUp API interactions go through the `ClickupRepository` interface\n2. **Use Case Pattern**: Business logic is isolated in dedicated use case classes\n3. **Type Safety**: Comprehensive TypeScript types in `src/types/` ensure API contracts are maintained\n4. **MCP Integration**: Tools are registered in `src/server/mcp-server.ts`\n5. **Clean Architecture**: Separation of concerns between domain, use cases, and infrastructure layers\n\n#### 🏗️ Scalability Considerations\n\n- **Modular Structure**: Each feature can be developed independently\n- **Dependency Injection**: Easy to test and mock external dependencies\n- **Error Boundaries**: Consistent error handling across all API operations\n- **Configuration Management**: Centralized config supports multiple API keys/teams\n\n#### 🔄 Future Architecture Enhancements\n\n- **Caching Layer**: Redis/memory cache for frequently accessed tasks\n- **Rate Limiting**: Built-in ClickUp API rate limit management\n- **Webhook Support**: Real-time notifications from ClickUp\n- **Bulk Operations**: Batch processing for multiple task operations\n\n## 📋 Available Tools\n\n### Current Tools\n\n#### `getTaskByCustomId`\n\nRetrieves a ClickUp task by its Custom ID.\n\n**Parameters:**\n\n- `taskCustomId` (string): The Custom ID of the task (e.g., \"EXP-1234\")\n\n**Returns:**\n\n- Complete task details including name, description, status, assignees, custom fields, and attachments\n- Error message if task not found\n\n#### `getTaskComments`\n\nRetrieves all comments from a ClickUp task, formatted for easy reading.\n\n**Parameters:**\n\n- `taskCustomId` (string): The Custom ID of the task (e.g., \"EXP-1234\")\n\n**Returns:**\n\n- Formatted list of all task comments with user information, timestamps, and content\n- Support for rich content including images, links, and user mentions\n- Reply counts for each comment\n- \"No comments found\" message if task has no comments\n\n#### `getTaskCustomFieldDetail`\n\nRetrieves detailed information about a specific custom field in a list.\n\n**Parameters:**\n\n- `listId` (string): The ID of the list containing the custom field (e.g., \"123123123\")\n- `customFieldId` (string): The UUID of the custom field (e.g., \"3b3d716d-a4a4-44ee-8eb1-1a08453f29eb\")\n\n**Returns:**\n\n- Complete custom field configuration including name, type, options, and validation rules\n- Error message if custom field not found\n\n### 🚧 Planned Tools (Coming Soon)\n\nThe following tools are planned for future releases to provide comprehensive ClickUp integration:\n\n#### `addTaskComment`\n\nAdd comments to ClickUp tasks.\n\n- **Parameters**: `customId`, `comment`, `assignee` (optional)\n- **Use case**: AI assistants can add progress updates, notes, or follow-up comments\n\n#### `updateTaskStatus`\n\nUpdate the status of ClickUp tasks.\n\n- **Parameters**: `customId`, `status`\n- **Use case**: AI assistants can move tasks through workflow stages\n\n#### `createTask`\n\nCreate new ClickUp tasks.\n\n- **Parameters**: `name`, `description`, `listId`, `priority` (optional), `assignee` (optional)\n- **Use case**: AI assistants can create tasks from conversations or requirements\n\n#### `getTasksByStatus`\n\nRetrieve tasks filtered by status.\n\n- **Parameters**: `status`, `listId` (optional)\n- **Use case**: AI-powered status reports and task management dashboards\n\n### CLI Options\n\nThe server supports the following command line options:\n\n- `--api-key <key>`: ClickUp API key (alternative to `CLICKUP_API_KEY` env var)\n- `--team-id <id>`: ClickUp team ID (alternative to `CLICKUP_TEAM_ID` env var)\n- `--help`: Show usage information\n\n**Example:**\n\n```bash\nnode build/index.js --api-key pk_123... --team-id 12345\n```\n\n## 🔒 Security\n\n- **API credentials** are loaded from environment variables\n- **No sensitive data** is logged or exposed\n- **Read-only access** to ClickUp data\n- **Standard HTTPS** communication with ClickUp API\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### Reporting Issues\n\n- **Bug reports**: Include steps to reproduce, expected vs actual behavior\n- **Feature requests**: Describe the use case and proposed solution\n- **Questions**: Use GitHub Discussions for general questions\n\n### Contributing Code\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Follow the existing architecture patterns**\n4. **Add tests** for new functionality\n5. **Update documentation** as needed\n6. **Submit a Pull Request**\n\n### Development Guidelines\n\n- **Clean Architecture**: Follow the existing layered approach\n- **TypeScript**: Use proper typing throughout\n- **Error Handling**: Include comprehensive error handling\n- **Documentation**: Update README and code comments\n- **Testing**: Add unit tests for new features\n\n### Adding New API Tools\n\nWhen implementing new ClickUp API tools, follow these patterns:\n\n1. **Domain Layer**: Update the `ClickupRepository` interface in `src/domain/clickup.ts` if needed\n2. **Types**: Add new entity types to `src/types/entities.ts` and API response types to `src/types/api-responses.ts`\n3. **Use Cases**: Create new use case files in `src/use-cases/` for business logic\n4. **Repository**: Extend `src/infra/clickup-repository.ts` with new API methods\n5. **Export**: Add new use cases to `src/use-cases/index.ts`\n6. **MCP Registration**: Register new tools in `src/server/mcp-server.ts`\n\n### Code Style\n\n- Use **ESLint** and **Prettier** configurations\n- Follow **conventional commit** messages\n- Keep **functions small** and focused\n- Use **meaningful variable names**\n- Add **JSDoc comments** for public APIs\n\n## 📄 License\n\nMIT License - see [LICENSE](../LICENSE) file for details.\n\n## 🔗 Links\n\n- **MCP Protocol**: [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/)\n- **ClickUp API**: [https://clickup.com/api](https://clickup.com/api)\n- **Claude Desktop**: [https://claude.ai/](https://claude.ai/)\n- **Repository**: [https://github.com/csevero/mcp-servers](https://github.com/csevero/mcp-servers)\n\n---\n\n**Questions?** Open an issue or start a discussion in the main repository!\n","readmeFilename":"README.md"}