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).

Quick Start (macOS)

Follow these steps in order to get RescueTime MCP working with Claude Desktop:

Step 1: Get Your RescueTime API Key

Log in to your RescueTime account
Go to https://www.rescuetime.com/anapi/manage
Generate or copy your existing API key (you'll need this for Step 3)

Step 2: Clone and Set Up the Project

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

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install the package in editable mode
pip install -e .

Step 3: Create Your Configuration File

Create a .env file in the project root with your API key:

echo "RESCUETIME_API_KEY=your_api_key_here" > .env

Replace your_api_key_here with your actual RescueTime API key from Step 1.

Step 4: Note Your Installation Path

# Get the full path to your installation (you'll need this for Step 5)
pwd
# This will output something like: /Users/yourname/projects/rescuetime-mcp

Step 5: Configure Claude Desktop

Open your Claude Desktop configuration file:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add this configuration, replacing /path/from/step4 with your actual path:

{
  "mcpServers": {
    "rescuetime": {
      "command": "/path/from/step4/venv/bin/python",
      "args": ["-m", "rescuetime_mcp.server"]
    }
  }
}

For example, if your path from Step 4 was /Users/john/projects/rescuetime-mcp, your config would look like:

{
  "mcpServers": {
    "rescuetime": {
      "command": "/Users/john/projects/rescuetime-mcp/venv/bin/python",
      "args": ["-m", "rescuetime_mcp.server"]
    }
  }
}

Step 6: Restart Claude Desktop

Quit Claude Desktop completely and restart it.

Step 7: Test It Works

In Claude Desktop, try asking:

"Check my RescueTime productivity data for today"
"Start a 25-minute focus session"
"Show me my daily productivity summary"

If Claude can access your RescueTime data, you're all set!

Available Commands in Claude

Once configured, you can ask Claude to:

Core Functions

Get productivity data: "Show me my RescueTime data for the last week"
Daily summaries: "Get my daily productivity summary" (Note: Has ~24 hour delay, returns previous days only)
Manage alerts: "Show me my RescueTime alerts"
Create highlights: "Add a highlight for completing the project presentation"
Focus sessions: "Start a 45-minute focus session" or "End my focus session"
Log offline time: "Log 2 hours of offline coding work"
Check status: "Is my focus session still active?"

Convenience Functions

Today's productivity score: "What's my productivity score today?" (Real-time data)
Top distractions: "Show me my top distracting activities today"
Latest daily summary: "Get the most recent daily summary" (Usually yesterday's data)

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

Advanced Configuration

Alternative API Key Methods

While the .env file is recommended, you can also:

Set in Claude Desktop config (if you prefer not to use .env):

{
  "mcpServers": {
    "rescuetime": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "rescuetime_mcp.server"],
      "env": {
        "RESCUETIME_API_KEY": "your_api_key_here"
      }
    }
  }
}

Use system environment variable:

export RESCUETIME_API_KEY="your_api_key_here"

Windows Installation

The steps are similar, but use:

python -m venv venv instead of python3
venv\Scripts\activate instead of source venv/bin/activate
Config file location: %APPDATA%\Claude\claude_desktop_config.json

Development

Running Tests

# Activate virtual environment first
source venv/bin/activate

# Run all tests
pytest

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

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

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.

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!

Rescuetime MCP

Install / Use

README