Content
⚠️ **PRIVATE REPOSITORY NOTICE** ⚠️
This is a private repository for SimHop IT & Media AB team members only. While the code is available for viewing and use under the MIT license, we do not accept public contributions at this time. You are welcome to fork the repository and create your own version, as long as it's not identical or extremely similar to our package to avoid user confusion.
# <span style="color: #A351D6">🤘 Claudeus Plane MCP</span> 🎸
> *"Unleash the Power of AI in Your Plane Realm - Setting the Standard for MCP Excellence!"* <span style="color: #000000">🖤</span>
[](https://github.com/deus-h/claudeus-plane-mcp/stargazers)
[](https://www.npmjs.com/package/claudeus-plane-mcp)
[](https://www.npmjs.com/package/claudeus-plane-mcp)
[](https://github.com/deus-h/claudeus-plane-mcp/discussions)
[](https://github.com/deus-h/claudeus-plane-mcp/network)
[](https://smithery.ai/server/claudeus-plane-mcp)
[](https://github.com/deus-h/claudeus-plane-mcp)
[](https://github.com/deus-h/claudeus-plane-mcp)
## 🎯 Our Mission: Elevating Project Management with AI
In the rapidly evolving landscape of AI-powered project management, we're introducing Claudeus Plane MCP - a powerful bridge between Claude's AI capabilities and Plane's project management platform. Our mission is to:
- ✅ Provide seamless AI integration with Plane
- ✅ Enable automated project management workflows
- ✅ Enhance team collaboration through AI assistance
- ✅ Streamline task and resource management
- ✅ Set new standards for MCP development
### Why Claudeus Plane MCP?
Built on the foundation of our successful Claudeus WordPress MCP, this server brings the same level of:
- 🎸 Technical Excellence: Complete TypeScript coverage with strict type checking
- 🎸 Quality Assurance: Comprehensive test suite (95%+ coverage)
- 🎸 Protocol Compliance: Full MCP 2024-11-05 specification implementation
- 🎸 Security: Enterprise-grade security practices
- 🎸 Reliability: Robust error handling and recovery
- 🎸 Documentation: Detailed guides and examples
### 🤘 Why We Chose Plane: The Technical Symphony
In the vast landscape of project management solutions, our choice of Plane wasn't just a decision - it was a technical revelation. Here's why Plane stands out as the perfect foundation for our AI-powered project management revolution:
#### 🎸 Technical Excellence & Architecture
1. **Open Source Power**
- Full source code transparency
- AGPL v3.0 license ensuring freedom
- Active community contributions
- Self-hosting capabilities with Docker/Kubernetes
2. **Modern Tech Stack**
- Built with cutting-edge technologies
- Clean, modular architecture
- Extensible plugin system
- API-first design philosophy
3. **Performance & Scalability**
- Lightning-fast response times
- Efficient database operations
- Smart caching mechanisms
- Horizontal scaling support
#### 🎯 Feature Flexibility
Unlike traditional solutions that force you into their workflow:
| Feature | Plane | Others |
|---------|--------|---------|
| **Workflow Flexibility** | Adapt to any methodology (Agile, Waterfall, etc.) | Often locked into specific methodologies |
| **Customization** | Fully customizable with open architecture | Limited to vendor-provided options |
| **Integration** | Open API with complete access | Often restricted or paid APIs |
| **Self-Hosting** | Full control over data and infrastructure | Usually cloud-only or limited self-hosting |
#### ⚡ Development Velocity
Plane's architecture enables:
- **Rapid Iteration**: Quick feature development and deployment
- **Easy Extension**: Simple plugin development
- **API Excellence**: Complete REST API coverage
- **Real-time Updates**: WebSocket support for live changes
#### 🔒 Security & Control
1. **Data Sovereignty**
- Complete control over data location
- No vendor lock-in
- Custom security policies
- Compliance flexibility
2. **Authentication & Authorization**
- Granular permission system
- Multiple auth methods
- Role-based access control
- API key management
#### 💰 Cost-Effectiveness
| Aspect | Plane | Traditional Solutions |
|--------|-------|----------------------|
| Licensing | Open Source | Often expensive per-user pricing |
| Hosting | Self-hosted options | Usually cloud-only |
| Customization | Free and unlimited | Often requires paid add-ons |
| API Usage | Unlimited | Usually metered/limited |
#### 🚀 Future-Ready Architecture
Plane's design aligns perfectly with modern development needs:
1. **AI Integration Ready**
- Clean API design perfect for AI integration
- Structured data model ideal for ML
- Extensible architecture for AI features
- Real-time capabilities for AI assistance
2. **Modern Development**
- TypeScript/Python backend
- React-based frontend
- Docker containerization
- Kubernetes orchestration
3. **Community Power**
- Active development community
- Regular updates and improvements
- Open to contributions
- Transparent roadmap
#### 🎸 The Metal Factor
Just like heavy metal breaks free from conventional musical boundaries, Plane breaks free from traditional project management constraints:
- **Freedom**: Like writing your own riffs instead of playing covers
- **Power**: Full control over your project management destiny
- **Innovation**: Ability to create new workflows and features
- **Community**: Strong open-source spirit, just like the metal community
> 🤘 "In a world of corporate project management, Plane is like that underground metal band that changes the game - raw, powerful, and completely authentic!" - Amadeus
#### 🔮 Partnership Potential
Plane's philosophy aligns perfectly with our vision:
1. **Open Source Excellence**
- Both companies value transparency
- Shared commitment to quality
- Community-driven development
2. **Innovation Focus**
- AI-first thinking
- Modern architecture
- Continuous evolution
3. **Technical Synergy**
- API-driven development
- Modern tech stack
- Performance focus
This is why Plane isn't just our choice - it's our technical soulmate in the project management realm. Together with our AI integration through Claudeus Plane MCP, we're creating a symphony of efficiency that rocks the project management world! 🤘
## 🚀 Core Features
### 🎯 Project Management
- Create and manage projects with AI assistance
- Automated project setup and configuration
- Smart project templates and workflows
### 📋 Task Management
- AI-powered task creation and assignment
- Automated task prioritization
- Smart task dependencies management
### 👥 Team Collaboration
- Intelligent resource allocation
- Automated team notifications
- Smart workload balancing
### 💬 Communication
- AI-enhanced comment management
- Smart notification systems
- Automated status updates
## 📖 Quick Start Guide
### Prerequisites
```bash
# Required Software
Node.js ≥ 22.0.0
TypeScript ≥ 5.0.0
PNPM
Plane instance with API access
```
### Installation
```bash
# Clone the repository
git clone https://github.com/deus-h/claudeus-plane-mcp
# Install dependencies
pnpm install
# Build the project
pnpm build
# Configure Claude Desktop
cp claude_desktop_config.json.example claude_desktop_config.json
# Edit claude_desktop_config.json with your settings
```
### Configuration
```bash
# Copy example configs
cp .env.example .env
cp plane-instances.json.example plane-instances.json
# Edit .env and plane-instances.json with your settings
```
### Configuring plane-instances.json
The `plane-instances.json` file is used to configure your Plane instances for integration. Below is an example structure:
```json
{
"instance-alias": {
"baseUrl": "https://your-plane-instance.com/api/v1",
"defaultWorkspace": "your-workspace-slug",
"otherWorkspaces": ["workspace2", "workspace3"],
"apiKey": "your-plane-api-key"
}
}
```
#### Configuration Fields
- **baseUrl**: The base URL of your Plane API (required)
- **defaultWorkspace**: The default workspace slug (required)
- **otherWorkspaces**: Array of additional workspace slugs (optional)
- **apiKey**: Your Plane API key (required)
## 🛠️ Development
### Project Structure
```typescript
src/
├── api/ # Plane API integration
│ ├── client/ # API client implementation
│ ├── endpoints/ # Endpoint definitions
│ └── types/ # API type definitions
│
├── mcp/ # MCP protocol implementation
│ ├── server.ts # Core MCP server
│ ├── transport/ # Transport handlers
│ ├── tools.ts # Tool definitions
│ └── types/ # MCP type definitions
│
├── tools/ # Tool implementations
│ ├── projects/ # Project management
│ ├── tasks/ # Task operations
│ ├── users/ # User management
│ └── comments/ # Comment handling
│
└── prompts/ # AI prompt templates
├── projects/ # Project-related prompts
├── tasks/ # Task-related prompts
└── analysis/ # Analysis prompts
```
### Available Scripts
```bash
# Development
pnpm dev # Start development server
pnpm watch # Watch for changes
pnpm inspector # Launch MCP Inspector
# Testing
pnpm test # Run tests
pnpm test:watch # Watch tests
pnpm test:coverage # Generate coverage
# Building
pnpm build # Build for production
pnpm clean # Clean build files
```
## 🔒 Security
### Authentication
- API Key-based authentication
- Secure token management
- Request validation
### Data Protection
- Encrypted communication
- Secure configuration storage
- Input sanitization
## 🤝 Contributing
This is a private repository maintained by the SimHop IT & Media AB development team. While we don't accept public contributions, team members can contribute following our development standards:
1. Create feature branches (`feature/AmazingFeature`)
2. Maintain test coverage above 95%
3. Follow our TypeScript and documentation standards
4. Submit PRs for review
## 📄 License
MIT License - Copyright (c) 2024 SimHop IT & Media AB
## 🎸 The Team Behind the Magic
### SimHop IT & Media AB - Where Innovation Meets Metal 🤘
Based in Sweden, SimHop IT & Media AB brings together technical excellence and creative innovation. Our team includes:
**Amadeus Samiel H. (CTO/Lead Solutions Architect)**
- MSc in Computer Science
- 20+ years of technical excellence
- The virtuoso behind Claudeus MCP servers
**Simon Malki (CEO)**
- 20+ years of business leadership
- Strategic planning expert
- The visionary driving SimHop's success
> Made with 🤘❤️ by [<span style="color: #A351D6">Amadeus Samiel H.</span>](mailto:amadeus.hritani@simhop.se)
## 🛠 MCP Tools Reference
### Tool Categories and Danger Levels
| Tool Name | Category | Capabilities | Danger Level |
|-----------|----------|--------------|--------------|
| **Project Management** ||||
| `claudeus_plane_projects__list` | Projects | List all projects | 🟢 Safe |
| `claudeus_plane_projects__create` | Projects | Create new projects | 🟡 Moderate |
| `claudeus_plane_projects__update` | Projects | Modify projects | 🟡 Moderate |
| `claudeus_plane_projects__delete` | Projects | Remove projects | 🔴 High |
| **Task Management** ||||
| `claudeus_plane_tasks__list` | Tasks | List all tasks | 🟢 Safe |
| `claudeus_plane_tasks__create` | Tasks | Create new tasks | 🟡 Moderate |
| `claudeus_plane_tasks__update` | Tasks | Modify tasks | 🟡 Moderate |
| `claudeus_plane_tasks__delete` | Tasks | Remove tasks | 🔴 High |
| **User Management** ||||
| `claudeus_plane_users__list` | Users | List all users | 🟢 Safe |
| `claudeus_plane_users__invite` | Users | Invite new users | 🟡 Moderate |
| `claudeus_plane_users__update` | Users | Modify user roles | 🟡 Moderate |
| `claudeus_plane_users__remove` | Users | Remove users | 🔴 High |
| **Comment Management** ||||
| `claudeus_plane_comments__list` | Comments | List all comments | 🟢 Safe |
| `claudeus_plane_comments__create` | Comments | Create comments | 🟡 Moderate |
| `claudeus_plane_comments__update` | Comments | Edit comments | 🟡 Moderate |
| `claudeus_plane_comments__delete` | Comments | Remove comments | 🔴 High |
### Danger Level Legend
- <span style="color: #00ff00">🟢 **Safe**: Read-only operations, no data modification</span>
- <span style="color: #ffff00">🟡 **Moderate**: Creates or modifies content, but can be reverted</span>
- <span style="color: #ff0000">🔴 **High**: Destructive operations or system-wide changes</span>
## 🎯 Technical Deep Dive
### Architecture Overview 🏗️
Each component in our technical architecture is designed for maximum efficiency and reliability:
#### Core Components 🤘
| Component | Responsibility | Key Features |
|-----------|---------------|--------------|
| **API Layer** | Plane Integration | REST client, Type safety, Rate limiting |
| **MCP Protocol** | Communication | JSON-RPC 2.0, Bi-directional flow |
| **Security** | Protection | Auth, Encryption, Validation |
| **Tools** | Operations | Projects, Tasks, Users, Comments |
| **Prompts** | AI Integration | Templates, Context awareness |
#### Technical Implementation 🎸
| Feature | Implementation | Description |
|---------|---------------|-------------|
| **Type Safety** | TypeScript | Full static typing, Runtime validation |
| **API Handling** | REST/JSON-RPC | Efficient request/response handling |
| **Event System** | EventEmitter | Async event processing |
| **Error Handling** | Multi-layer | Comprehensive error management |
| **Caching** | In-memory/Redis | Performance optimization |
#### Security Measures 🛡️
| Layer | Protection | Features |
|-------|------------|-----------|
| **Transport** | TLS/SSL | Encrypted communication |
| **Authentication** | API Key | Secure token management |
| **Validation** | Schema-based | Input/Output validation |
| **Encryption** | AES-256 | Data protection |
| **Audit** | Comprehensive | Activity tracking |
#### Performance Tuning 🚀
| Optimization | Technique | Description |
|-------------|-----------|-------------|
| **Caching** | Multi-level | Response & Query caching |
| **Batching** | Request grouping | Reduced API calls |
| **Compression** | GZIP/Brotli | Network optimization |
| **Query Optimization** | Smart fetching | Efficient API queries |
| **Load Balancing** | Distribution | Scale handling |
#### Error Categories & Handling 🎸
| Category | Code Range | Handling | Example |
|----------|------------|----------|---------|
| **Protocol** | -32600 to -32603 | Auto-retry | Invalid JSON-RPC |
| **Plane API** | 1000-1999 | Fallback | API timeout |
| **Security** | 2000-2999 | Alert | Auth failure |
| **Tools** | 3000-3999 | Recover | Operation fail |
| **System** | 4000-4999 | Restart | Resource exhaustion |
### Design Principles Power Chord 🤘
| Principle | Description | Implementation |
|-----------|-------------|----------------|
| **Modularity** | Loose coupling | Independent components |
| **Type Safety** | Strong typing | TypeScript + Validation |
| **Security** | Zero trust | Multi-layer protection |
| **Performance** | Speed metal | Optimized operations |
> 🎸 Pro Tip: Like a well-tuned guitar, each component is precisely calibrated for maximum shredding capability! ❤️
## ⚡ Performance Metrics
### Time Savings
| Task | Manual Process | With Claudeus | Result |
|------|---------------|---------------|---------|
| Project Setup | 2 hours | 2 mins | <span style="color: #00ff00">✓ 98.3%</span> |
| Task Creation | 30 mins | 30 secs | <span style="color: #00ff00">✓ 98.3%</span> |
| User Management | 1 hour | 1 min | <span style="color: #00ff00">✓ 98.3%</span> |
| Bulk Updates | 4 hours | 3 mins | <span style="color: #00ff00">✓ 98.7%</span> |
### Cost Efficiency
| Resource | Traditional Cost | Description |
|----------|-----------------|-------------|
| Project Manager | $5000/month | Project setup and management |
| Task Manager | $3000/month | Task tracking and updates |
| Team Lead | $4000/month | Resource allocation |
| **TOTAL** | **<span style="color: #ff0000">$12,000/month</span>** | All services combined |
| | | |
| **Claude Pro** | **<span style="color: #A351D6">$20/month</span>** | At [Anthropic](https://claude.ai/settings/billing?action=subscribe) |
| | | |
| **Difference** | **<span style="color: #00ff00">$11,980/month</span>** | Potential Savings using <span style="color: #00ff00">**Claudeus Plane MCP**</span> <br> with <span style="color: #00ff00">Claude Desktop</span> ([Mac](https://storage.googleapis.com/osprey-downloads-c02f6a0d-347c-492b-a752-3e0651722e97/nest/Claude.dmg), [Windows](https://storage.googleapis.com/osprey-downloads-c02f6a0d-347c-492b-a752-3e0651722e97/nest-win-x64/Claude-Setup-x64.exe)) |
## 🎸 Claude Desktop Integration
### Configuration Location
The Claude Desktop configuration file can be found at:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
⚠️ **IMPORTANT**: If you already have other MCP servers configured in Claude Desktop, DO NOT directly copy our example file as it will overwrite your existing configuration! Instead:
1. **For existing Claude Desktop users**:
- Open your existing config through Claude Desktop:
- Click on the Claude menu
- Select "Settings..."
- Click on "Developer" in the lefthand bar
- Click on "Edit Config"
- OR open your config file directly in a text editor
- Add our Claudeus Plane MCP server configuration to your existing `mcpServers` object
2. **For new Claude Desktop users**:
You can copy our example config file:
```bash
# For macOS
cp claude_desktop_config.json.example ~/Library/Application\ Support/Claude/claude_desktop_config.json
# For Windows (in PowerShell)
Copy-Item claude_desktop_config.json.example $env:APPDATA\Claude\claude_desktop_config.json
```
### Configuration Examples
#### NPX Setup
```json
{
"mcpServers": {
"claudeus-plane-mcp": {
"command": "npx",
"args": [
"-y",
"claudeus-plane-mcp"
],
"env": {
"PLANE_INSTANCES_PATH": "/absolute/path/to/your/plane-instances.json"
}
}
}
}
```
#### Docker Setup 🐳
```json
{
"mcpServers": {
"claudeus-plane-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--network=host",
"--mount", "type=bind,src=/absolute/path/to/your/plane-instances.json,dst=/app/plane-instances.json",
"--mount", "type=bind,src=/absolute/path/to/your/.env,dst=/app/.env",
"mcp/plane",
"--config", "/app/plane-instances.json"
]
}
}
}
```
> 🎸 Pro Tip: Make sure to replace `/absolute/path/to/your/plane-instances.json` with the actual path to your configuration file!
### After Configuration
1. Restart Claude Desktop completely
2. Look for the hammer 🔨 icon in the bottom right corner of the input box
3. Click it to see available Plane management tools
4. Start shredding! 🤘
### Troubleshooting
If the server isn't showing up in Claude:
1. Verify your `claude_desktop_config.json` syntax
2. Ensure file paths are absolute and valid
3. Check Claude's logs at:
- macOS: `~/Library/Logs/Claude`
- Windows: `%APPDATA%\Claude\logs`
## ⚠️ Issues and Considerations
### Current Limitations and Workarounds
#### 1. Claude Desktop Response Limits
- **Issue**: Claude Desktop's maximum response length can be reached during complex operations
- **Impact**: Operations may be interrupted, requiring user intervention
- **Workaround**:
- Configure Claude Desktop to break tasks into smaller batches
- In Claude Desktop Settings > Advanced:
- Set "Maximum Response Length" to a lower value
- Enable "Auto-split Responses"
- Use the Inspector UI for large-scale operations
#### 2. Rate Limiting Considerations
- **Issue**: Plane API has rate limits
- **Impact**: Bulk operations might be throttled
- **Mitigation**:
- Use batch processing features
- Implement appropriate delays between requests
- Monitor API response headers for rate limit info
#### 3. Memory Management
- **Issue**: Large operations can consume significant memory
- **Impact**: Potential performance degradation
- **Best Practices**:
- Monitor system resources during large operations
- Use pagination for large datasets
- Implement cleanup routines
### Future Improvements
We're actively working on:
1. Improved response handling in Claude Desktop
2. Advanced rate limiting management
3. Memory optimization techniques
4. Enhanced error recovery mechanisms
> 🎸 Pro Tip: Check our GitHub Discussions for workarounds and best practices!
## 🎸 Support and Community ❤️
- GitHub Discussions: Share ideas, report issues, and join the conversation
- Documentation: Full technical docs
- Examples: Sample implementations
> 🎸 Pro Tip: Use GitHub Discussions to share your experience, report issues, or suggest improvements!
---
### The Project Manager's Anthem
#### *by Amadeus & Claude*
---
*In Plane's vast space,
Tasks flow with grace,
AI's embrace,
Sets perfect pace.*
*Through Claude's might,
Projects take flight,
In code's delight,
All syncs just right.*
*A manager's dream,
Where AI and team,
Work upstream,
Like metal's gleam.*
---
> Made with 🤘❤️ by [<span style="color: #A351D6">Amadeus Samiel H.</span>](mailto:amadeus.hritani@simhop.se)
