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
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 python3venv\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.
Copyright © 2025 Eric Bowman
Acknowledgments
Special thanks to the FastMCP community and RescueTime for providing robust APIs.
Support
Getting Help
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!