RescueTime MCP Server

A comprehensive FastMCP server for integrating with the RescueTime API, providing tools to access productivity data, manage focus sessions, and interact with all RescueTime features through the Model Context Protocol (MCP).

Table of Contents

• Features
• Supported RescueTime APIs
• Installation
• Configuration
• Usage
• Development
• Contributing
• License

Features

• Complete RescueTime API Coverage: Access all major RescueTime APIs including analytic data, daily summaries, alerts, highlights, focus sessions, and offline time tracking
• FastMCP Integration: Built on the FastMCP framework for robust MCP server functionality
• Async Support: Full asynchronous support for high-performance operations
• Type Safety: Comprehensive type hints and Pydantic models for data validation
• Error Handling: Robust error handling with custom exceptions and logging
• Comprehensive Testing: Full test suite including unit tests, integration tests, and performance tests

Supported RescueTime APIs

1. Analytic Data API

• Get detailed productivity analytics with customizable time ranges and filters
• Support for different perspectives (rank, interval, member) and resolutions

2. Daily Summary Feed API

• Access daily productivity summaries and pulse scores
• Filter by date ranges

3. Alerts Feed API

• Retrieve and manage productivity alerts
• Dismiss unwanted alerts

4. Highlights Feed/POST API

• View existing highlights
• Create new productivity highlights

5. FocusTime APIs

• Start and end focus sessions
• Monitor current focus session status
• Set custom focus duration

6. Offline Time POST API

• Log offline work time
• Add descriptions for offline activities

Installation

Prerequisites

• Python 3.9 or higher
• RescueTime account with API access
• RescueTime API key

Install from Source

# Clone the repository
git clone https://github.com/ebowman/rescuetime-mcp.git
cd rescuetime-mcp

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# For users - install basic package
pip install -e .

# For developers - install with development tools
pip install -e ".[dev]"

Configuration

Environment Variables

Set your RescueTime API key as an environment variable:

export RESCUETIME_API_KEY="your_rescuetime_api_key_here"

Alternatively, create a .env file in the project root:

RESCUETIME_API_KEY=your_rescuetime_api_key_here

Getting Your API Key

1. Log in to your RescueTime account
2. Go to https://www.rescuetime.com/anapi/manage
3. Generate or copy your existing API key

Usage

Running the MCP Server

# Run directly
rescuetime-mcp

# Or using Python module
python -m rescuetime_mcp.server

# Check version
rescuetime-mcp --version

Available MCP Tools

• get_analytic_data - Get detailed productivity analytics with filters
• get_daily_summary_feed - Access daily productivity summaries
• get_alerts_feed - Retrieve productivity alerts
• dismiss_alert - Dismiss specific alerts
• get_highlights_feed - View productivity highlights
• post_highlight - Create new highlights
• start_focus_session - Start FocusTime sessions
• end_focus_session - End current focus session
• get_focus_session_status - Check focus session status
• post_offline_time - Log offline work time
• health_check - Verify API connection

Development

# Create virtual environment  
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install with development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=rescuetime_mcp --cov-report=html

# Run only unit tests
pytest tests/test_client.py tests/test_server.py

# Run integration tests (requires real API key)
export RESCUETIME_API_KEY_REAL="your_real_api_key"
pytest tests/test_integration.py -m integration

# Run performance tests
pytest tests/test_integration.py -m slow

Code Quality

# Format code
black src tests

# Sort imports
isort src tests

# Lint code
ruff check src tests

# Type checking
mypy src

Project Structure

rescuetime-mcp/
├── src/rescuetime_mcp/
│   ├── __init__.py          # Package initialization
│   ├── client.py            # RescueTime API client
│   └── server.py            # FastMCP server implementation
├── tests/
│   ├── conftest.py          # Test configuration
│   ├── test_client.py       # Client tests  
│   ├── test_server.py       # Server tests
│   └── test_integration.py  # Integration tests
└── pyproject.toml           # Project configuration

Contributing

See CONTRIBUTING.md for development setup, code standards, and contribution guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright © 2025 Eric Bowman

Acknowledgments

• Built with FastMCP framework
• Uses RescueTime API
• Powered by Pydantic for data validation
• HTTP client powered by httpx

Special thanks to the FastMCP community and RescueTime for providing robust APIs.

Support

Getting Help

• Documentation: This README and inline code documentation
• Bug Reports: Use GitHub Issues
• Feature Requests: Create an issue with detailed use cases
• Questions: Use GitHub Discussions
• Security: Email ebowman@boboco.ie for security-related issues

Project Status

This project is actively maintained. We aim to respond to issues and pull requests promptly.

• Latest Version: v0.1.0
• Python Support: 3.9+
• Status: Beta Release

Changelog

See CHANGELOG.md for detailed version history and changes.

---

Made with ❤️ by Eric Bowman

If this project helps you, please consider giving it a ⭐ on GitHub!