Nuclino MCP Server

Enterprise-grade Model Context Protocol (MCP) server for Nuclino API integration with Claude Desktop. Features advanced rate limiting, intelligent caching, and comprehensive error handling.

⚡ Quick Start

Prerequisites

• Go 1.21+
• Mage - go install github.com/magefile/mage@latest
• Nuclino API key - Get yours here

Installation

git clone https://github.com/lukasz/nuclino-mcp.git
cd nuclino-mcp
mage install  # Install dependencies
cp .env.example .env  # Add your NUCLINO_API_KEY
mage build

Claude Desktop Setup

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "nuclino": {
      "command": "/full/path/to/nuclino-mcp/scripts/mcp-wrapper.sh",
      "args": ["/full/path/to/nuclino-mcp/bin/nuclino-mcp-server"],
      "env": {
        "NUCLINO_API_KEY": "your_api_key_here"
      }
    }
  }
}

💡 Important: Use the wrapper script to prevent JSON-RPC protocol issues with Claude Desktop.

📖 Complete Setup Guide

🛠 Features

✅ 18 Working MCP Tools

• Items: Create, read, update, delete, search, list
• Workspaces: List, get details, overview, content search
• Users/Teams: User info, team management
• Files: File listing and metadata

📊 API Status: 87% of core functionality working (based on official API testing)

🚀 Enterprise Features

• Rate Limiting: Circuit breaker pattern with adaptive control
• Intelligent Caching: TTL-based with LRU eviction
• Error Handling: Categorized errors with automatic retries
• Monitoring: Performance metrics and health checks
• Performance: Stress tested, benchmarked, memory-bounded

🎯 Usage Examples

Claude, list my Nuclino workspaces

Search for "API documentation" in my Nuclino workspace

Create a new item titled "Meeting Notes" with workspace_id "abc123"

Give me a comprehensive overview of workspace "workspace-123"

Update the item "item-456" with new content

Delete the old draft item "draft-789"

📚 Documentation

🧪 Development

Quick Commands

mage build        # Build binary
mage test         # Run all tests
mage dev          # Run with debug logging
mage ci           # Full CI pipeline

Testing

• Unit Tests: 18 working tools with comprehensive mocks
• Integration Tests: Multi-tool workflows
• API Testing: Real endpoint verification against production API
• Performance Tests: Stress testing and benchmarks
• Error Handling: Edge cases and failure scenarios

🔧 Configuration

# Required
NUCLINO_API_KEY=your_nuclino_api_key

# Optional (with defaults)
LOG_LEVEL=info           # debug, info, warn, error
RATE_LIMIT_RPS=10        # API requests per second  
HTTP_TIMEOUT=30s         # HTTP client timeout
CACHE_TTL=300s          # Cache expiration time
CACHE_SIZE=1000         # Maximum cache entries

🐛 Troubleshooting

Common Issues

📖 Full Troubleshooting Guide

📊 Project Status

Phase 5 Complete: Production Ready with Real API Integration

• ✅ MCP Server with official mcp-go library
• ✅ 18 Working tools with verified Nuclino API endpoints
• ✅ Real API testing against production Nuclino API
• ✅ Advanced rate limiting with circuit breaker pattern
• ✅ Intelligent caching with TTL and LRU eviction
• ✅ Comprehensive error handling with automatic retries
• ✅ Performance monitoring and health checks
• ✅ Extensive testing (unit + integration + performance + API)
• ✅ Cross-platform builds and CI/CD automation
• ✅ Complete documentation with working examples

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature-name
3. Add tests for new features
4. Run: mage ci (format, lint, test, build)
5. Submit pull request

📄 License

MIT License - see LICENSE file for details.

Built with ❤️ using Go and the official mcp-go library