Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Rize.io MCP Server what's my productivity like today?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Advanced productivity analytics integration with AI assistants through Model Context Protocol
A production-ready, enterprise-grade MCP server that seamlessly integrates Rize.io's powerful time tracking and productivity analytics with Claude Desktop and other AI assistants. Built with modern TypeScript architecture, comprehensive error handling, and performance optimization.
🌐 Portfolio Project: This server demonstrates advanced system architecture, API integration patterns, and enterprise-grade development practices for mariomosca.com.
Modular Service Layer: Separation of concerns with dedicated services for API, Auth, Cache, and Validation
GraphQL Integration: Advanced GraphQL client with query optimization and response caching
Comprehensive Logging: Winston-based logging with file rotation and structured error tracking
Type Safety: Full TypeScript implementation with Zod validation schemas
Performance Optimization: LRU caching with configurable TTL and intelligent cache invalidation
Authentication Service: Secure API key management with token validation
Input Validation: Comprehensive parameter validation using Zod schemas
Error Handling: Graceful error recovery with detailed error classification
Rate Limiting: Configurable request throttling and API quota management
Health Monitoring: Built-in health checks and system status reporting
Multi-Timeframe Analysis: Day, week, month analytics with trend analysis
Focus Session Intelligence: Deep session analysis with filtering and categorization
Productivity Insights: AI-powered insights generation and pattern recognition
Project Management: Complete project lifecycle management with metadata tracking
Real-time Metrics: Live productivity data with automated refresh intervals
Related MCP server: RescueTime MCP Server
Tool | Purpose | Key Features |
| Comprehensive productivity analysis | Date range filtering, category segmentation, trend analysis |
| Executive-level insights | Multi-timeframe views, AI-generated insights, performance trends |
| Daily performance overview | Category breakdown, context switching analysis, distraction metrics |
Tool | Purpose | Key Features |
| Detailed session analysis | Duration filtering, project correlation, productivity scoring |
| Project organization | Metadata management, category assignment, time tracking setup |
| Project portfolio overview | Pagination support, search capabilities, activity tracking |
Tool | Purpose | Key Features |
| User profile & preferences | Account validation, settings overview, usage statistics |
| System status monitoring | API connectivity, service health, performance metrics |
# Required Configuration
RIZE_API_KEY=your_rize_io_api_key # Your Rize.io API key
# Performance Optimization
CACHE_MAX_SIZE=1000 # LRU cache size (default: 1000)
CACHE_TTL=300000 # Cache TTL in ms (default: 5 minutes)
# Logging Configuration
LOG_LEVEL=info # Logging level (error, warn, info, debug)
# Rate Limiting
RATE_LIMITING=true # Enable rate limiting (default: true)
RATE_LIMIT_MAX=100 # Max requests per window (default: 100)
RATE_LIMIT_WINDOW=60000 # Rate limit window in ms (default: 1 minute)Clone & Install
git clone https://github.com/mariomosca/rizeio-mcp-server.git
cd rizeio_mcp_server
npm installConfiguration Setup
# Copy environment template
cp .env.example .env
# Edit configuration
nano .env # Add your Rize.io API key and adjust settingsBuild & Test
# Production build
npm run build
# Development mode with hot reload
npm run dev
# Run comprehensive tests
npm test~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"rize-productivity": {
"command": "node",
"args": ["/path/to/rizeio_mcp_server/dist/index.js"],
"env": {
"RIZE_API_KEY": "your_api_key_here",
"LOG_LEVEL": "info",
"CACHE_TTL": "300000"
}
}
}
}%APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"rize-productivity": {
"command": "node",
"args": ["C:\\path\\to\\rizeio_mcp_server\\dist\\index.js"],
"env": {
"RIZE_API_KEY": "your_api_key_here"
}
}
}
}Claude: "Show me my productivity summary for yesterday with category breakdown"
→ Uses get_productivity_summary tool
→ Returns comprehensive daily metrics with focus time, sessions, and distractionsClaude: "Generate a weekly analytics report with AI insights"
→ Uses get_analytics_report with timeframe="week" and includeInsights=true
→ Returns trend analysis, productivity patterns, and actionable recommendationsClaude: "Show me all focus sessions for my Development project this week, minimum 30 minutes"
→ Uses get_focus_sessions with projectId filter and minDuration=30
→ Returns filtered sessions with productivity metrics and time distributionClaude: "What are my most productive hours based on recent focus sessions?"
→ Combines multiple tool calls to analyze session patterns
→ Provides insights on optimal work scheduling and energy managementsrc/
├── services/
│ ├── rize-api.ts - GraphQL client & API integration
│ ├── auth.ts - Authentication & token management
│ ├── cache.ts - LRU caching with TTL support
│ └── validation.ts - Input validation & sanitization
├── utils/
│ ├── formatting.ts - Response formatting & presentation
│ ├── errors.ts - Custom error classes & handling
│ └── validation.ts - Zod schemas & input validation
├── types/
│ └── rize.ts - TypeScript interfaces & types
└── index.ts - Server initialization & tool registrationLRU (Least Recently Used) cache with configurable size limits
TTL-based expiration for time-sensitive data
Selective caching for performance-critical operations
Cache warming for frequently accessed data
Automatic invalidation on data mutations
Input Validation: Zod schema validation with detailed error messages
API Error Classification: Structured error types (Auth, Validation, Network, etc.)
Graceful Degradation: Fallback mechanisms for partial failures
Error Logging: Comprehensive error tracking with context and stack traces
User-Friendly Messages: Clean error presentation for AI assistant interaction
API Response Times: Track GraphQL query performance
Cache Hit Rates: Monitor caching effectiveness
Error Frequencies: Identify and track failure patterns
Memory Usage: Monitor cache size and memory consumption
Request Volume: Track API usage patterns and quotas
# Test server health
npm run health-check
# Response includes:
# - API connectivity status
# - Service health indicators
# - Performance metrics
# - Version information# Development server with hot reload
npm run dev
# MCP Inspector for testing
npm run inspector
# Linting and code quality
npm run lint
# Automated formatting
npm run format
# Comprehensive test suite
npm testAI-First API Design: Responses optimized for AI assistant parsing and understanding
Context-Aware Formatting: Intelligent data presentation based on request context
Natural Language Integration: Tools designed for conversational AI interaction patterns
Comprehensive Metadata: Rich data context that enables deeper AI analysis
Performance Optimization: Sub-second response times for real-time AI conversations
Pattern Recognition: Identify productivity patterns and trends across time periods
Predictive Insights: AI-generated recommendations based on historical data
Comparative Analysis: Cross-project and cross-timeframe performance comparisons
Behavioral Analytics: Deep insights into work habits and focus patterns
Optimization Suggestions: Data-driven recommendations for productivity improvements
This project showcases cutting-edge development practices:
Advanced Type System: Comprehensive type safety with complex generic types
Decorator Patterns: Elegant service composition and dependency injection
Async/Await Mastery: Sophisticated asynchronous operation handling
Error Boundary Design: Comprehensive error handling with recovery strategies
Microservice-Ready: Modular design suitable for distributed systems
API Gateway Patterns: Request routing and transformation capabilities
Event-Driven Architecture: Extensible event system for future integrations
Observability: Built-in monitoring, logging, and debugging capabilities
Memory Optimization: Efficient data structures and garbage collection patterns
Caching Strategies: Multi-layer caching with intelligent invalidation
Connection Pooling: Optimized API client management
Load Balancing Ready: Stateless design suitable for horizontal scaling
Real-time Notifications: WebSocket support for live productivity updates
Advanced Visualizations: Chart generation and data visualization tools
Machine Learning Integration: Predictive productivity modeling
Multi-Account Support: Enterprise team and organization management
Custom Analytics: User-defined metrics and KPI tracking
Integration Ecosystem: Connect with calendar, email, and task management tools
Webhook Support: Real-time event notifications and integrations
Batch Operations: Efficient bulk data processing and updates
Advanced Filtering: Complex query capabilities and search functions
Export Capabilities: Data export in multiple formats (CSV, JSON, PDF)
Historical Analysis: Long-term trend analysis and yearly comparisons
This MCP server demonstrates expertise in:
Enterprise-Grade Architecture: Production-ready system design and implementation
Advanced TypeScript Development: Complex type systems and modern JavaScript patterns
GraphQL Mastery: Efficient query optimization and response caching
Performance Engineering: Caching strategies, memory optimization, and scalability
API Integration Patterns: RESTful and GraphQL API consumption and management
Production Monitoring: Comprehensive logging, error handling, and health monitoring
AI-Assistant Integration: Optimized design for AI assistant interaction patterns
MIT License - see LICENSE file for details.
Contributions are welcome! Please read our Contributing Guide for development setup and submission guidelines.
Built with ⚡ by Mario Mosca - Demonstrating enterprise-grade AI integration architecture
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Project name | |
| description | No | Project description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| timeframe | Yes | Time frame for analytics (day, week, month) | |
| includeInsights | No | Include AI-generated insights |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| startDate | Yes | Start date (YYYY-MM-DD) | |
| endDate | Yes | End date (YYYY-MM-DD) | |
| projectId | No | Project ID filter | |
| category | No | Category filter (work, personal, all) | all |
| minDuration | No | Minimum session duration in minutes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| startDate | Yes | Start date (YYYY-MM-DD) | |
| endDate | Yes | End date (YYYY-MM-DD) | |
| category | No | Category filter (work, personal, all) | all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date for summary (YYYY-MM-DD) | |
| includeBreakdown | No | Include category breakdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of projects to return | |
| cursor | No | Pagination cursor |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0create_projectget_analytics_reportget_current_userget_focus_sessionsget_productivity_metricsget_productivity_summaryhealth_checklist_projectsScored across 8 tools
Tools like get_productivity_metrics and get_productivity_summary are likely overlapping, causing potential confusion. get_focus_sessions could also be related to productivity. However, other tools like create_project, list_projects, get_current_user, and health_check are distinct. Without descriptions, ambiguity is moderate.
Most tools follow a verb_noun pattern (get_*, create_*, list_*), but health_check breaks the pattern (noun_noun). Also, list_projects uses plural while create_project uses singular. This mixed convention is readable but inconsistent.
8 tools is an appropriate number for a productivity/analytics server. It covers core functionalities without being overwhelming or too sparse.
The domain appears to be project and productivity management. The set includes create and list for projects but lacks update/delete. For productivity, it only has get endpoints (sessions, metrics, summary) but no create or modify actions. This leaves notable gaps in CRUD coverage.
Privacy-first work tracking with summaries, reports, coaching, and AI-ready long-term memory.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Log hours and invoice clients from your AI chat. Time tracking and invoicing for freelancers.
Track billable time from your AI chat: timers, entries, reports, CSV export. All data stays local.
