🚀 Amazing Marvin AI Assistant Integration

Connect your Amazing Marvin productivity system with AI assistants for smarter task management

📋 Table of Contents

• What is this?
• Quick Start (2 minutes)
• What can you do with this?
• Installation
• Configuration
• Usage Examples
• Troubleshooting
• FAQ
• Development
• Privacy & Security

🎯 What is this?

This connects your Amazing Marvin productivity system with AI assistants like Claude, Cursor, and others. Instead of manually copying your tasks and projects into chat, your AI assistant can see and help with your actual Amazing Marvin data.

✨ Key Benefits

• 🔄 Stay in sync - Your AI assistant always sees your current tasks, projects, and goals
• 📋 Smart help - Get personalized advice based on your actual workload and priorities
• ⚡ Save time - No more copy-pasting task lists or explaining your projects
• 🎯 Better focus - AI helps you identify what's most important right now
• 🔒 Private - Your data stays between Amazing Marvin and your AI assistant

⚡ Quick Start (2 minutes)

Step 1: Get your Amazing Marvin API key

1. Open Amazing Marvin → Settings → API
2. Enable the API and copy your token
3. Keep this handy! 🔑

Step 2: Install

Easy way (Smithery):

npx -y @smithery/cli install @bgheneti/amazing-marvin-mcp --client claude

Paste the API key when prompted

Alternative (pip):

pip install amazing-marvin-mcp

Then add to your AI client config (see installation guide)

Step 3: Verify it's working

Ask your AI: "What tasks do I have today?"

🎉 That's it! Your AI can now see your Amazing Marvin data.

💡 What can you do with this?

Once connected, your AI assistant becomes your personal productivity coach with access to your real Amazing Marvin data:

📅 Daily Planning Help

"What should I focus on today?" - Get personalized recommendations based on your actual deadlines and priorities

"I'm feeling overwhelmed - what's most important?" - AI helps you cut through the noise and identify what really matters

🎯 Project Insights

"How is my website redesign project going?" - See progress, completed tasks, and what's left to do

"Show me everything related to client work this week" - Get organized views of your tasks by project or category

📊 Progress Tracking

"What did I accomplish this week?" - Review your productivity patterns and celebrate wins

"Which days am I most productive?" - Understand your patterns to plan better

⏰ Smart Scheduling

"What's overdue and needs attention?" - Never lose track of important deadlines

"Help me plan tomorrow based on what I have scheduled" - Get realistic daily plans that work

⏱️ Time Tracking

"Start tracking time on this task" - Seamlessly manage time tracking from your AI chat

"What have I been working on today?" - Review your time allocation and focus

Why this is better than generic productivity advice: Your AI sees your actual tasks, deadlines, and progress - so the help you get is personalized to your real situation, not generic tips.

Note: This covers most Amazing Marvin features, though some advanced customizations and strategies have limited API access.

📦 Installation

Option 1: Smithery (Easiest)

npx -y @smithery/cli install @bgheneti/amazing-marvin-mcp --client claude

Visit Smithery Registry for other clients.

Option 2: Pip + Manual Config

Why choose this option:

• ✅ Works with any MCP-compatible AI client
• ✅ Easy to update: just pip install --upgrade amazing-marvin-mcp

Prerequisites

• ✅ Python 3.10+
• ✅ Claude Desktop, Cursor, Windsurf, VS Code, or another MCP client
• ✅ Amazing Marvin account with API access

Installation

# Install from PyPI (recommended)
pip install amazing-marvin-mcp

📱 Client Configuration

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "python",
      "args": ["-m", "amazing_marvin_mcp"],
      "env": {
        "AMAZING_MARVIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "python",
      "args": ["-m", "amazing_marvin_mcp"],
      "env": {
        "AMAZING_MARVIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "python",
      "args": ["-m", "amazing_marvin_mcp"],
      "env": {
        "AMAZING_MARVIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "python",
      "args": ["-m", "amazing_marvin_mcp"],
      "env": {
        "AMAZING_MARVIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

💡 Usage Examples

The MCP provides specific tools that your AI can use. Simply ask your AI to help with productivity tasks and it will use the appropriate tools:

📁 How it understands your setup

Your AI assistant automatically understands your Amazing Marvin structure:

• Work & Personal projects - Keeps your professional and personal tasks organized
• Categories and labels - Knows how you've organized your productivity system
• Due dates and priorities - Understands what's urgent vs. important
• Completed vs. pending - Tracks your progress and momentum

No need to explain your system - your AI just gets it!

🔧 Troubleshooting

❌ Common Issues

❓ Common Questions

👨‍💻 Development

🛠️ Setup

git clone https://github.com/bgheneti/Amazing-Marvin-MCP.git
cd Amazing-Marvin-MCP
pip install -e ".[dev]"
pre-commit install

🔑 Set your API key

Option A: Environment variable

export AMAZING_MARVIN_API_KEY="your-api-key-here"

Option B: Create a .env file

AMAZING_MARVIN_API_KEY=your-api-key-here

🧪 Testing

pytest tests/ -v

⚠️ Note: Tests create temporary items in your Amazing Marvin account with [TEST] prefixes. These may need manual cleanup due to API limitations.

📋 Code Quality

# Run all checks
pre-commit run --all-files

# Individual tools
ruff check .          # Linting
ruff format .         # Formatting
mypy .               # Type checking
pytest tests/        # Tests

🔄 Available Tools

The MCP provides 28 comprehensive tools to AI assistants:

📖 Read Operations:

• get_daily_productivity_overview() - PRIMARY comprehensive daily view (today's tasks, overdue, completed, planning insights)
• get_tasks() - Today's scheduled items only
• get_projects() - All projects
• get_categories() - All categories
• get_due_items() - Overdue/due items only
• get_child_tasks( parent_id: str, recursive: bool = False ) - Subtasks of a parent task/project
• get_all_tasks( label: str = None ) - Find all tasks with optional label filter (comprehensive search)
• get_labels() - Task labels
• get_goals() - Goals and objectives
• get_account_info() - Account details
• get_completed_tasks() - Completed items with date categorization (defaults to past 7 days)
• get_completed_tasks_for_date( date: str ) - Completed items for specific date (YYYY-MM-DD format)
• get_productivity_summary_for_time_range( days: int = 7, start_date: str = None, end_date: str = None ) - Flexible productivity analytics
• get_currently_tracked_item() - Active time tracking

✏️ Write Operations:

• create_task( title: str, project_id: str = None, category_id: str = None, due_date: str = None, note: str = None ) - Create new tasks
• mark_task_done( item_id: str, timezone_offset: int = 0 ) - Complete tasks
• create_project( title: str, project_type: str = "project" ) - Create new projects
• start_time_tracking( task_id: str ) - Begin time tracking
• stop_time_tracking( task_id: str ) - End time tracking
• batch_mark_done( task_ids: list[str] ) - Complete multiple tasks
• batch_create_tasks( task_list: list[str], project_id: str = None, category_id: str = None ) - Create multiple tasks
• claim_reward_points( points: int, item_id: str, date: str ) - Claim kudos points
• get_kudos_info() - Get reward system and kudos information

🔧 Utility Operations:

• test_api_connection() - Verify API connectivity
• get_project_overview( project_id: str ) - Project analytics
• get_daily_focus() - Daily priorities
• get_productivity_summary() - Performance metrics
• time_tracking_summary() - Time analytics
• quick_daily_planning() - Planning assistance
• create_project_with_tasks( project_title: str, task_titles: list[str], project_type: str = "project" ) - Project setup
• get_time_tracks( task_ids: list[str] ) - Time tracking history

🤝 Contributing

🚀 Publishing New Versions

This project uses automated publishing to PyPI via GitHub Actions.

For maintainers:

# Make your changes and test them
pytest tests/ -v
ruff check src/
mypy src/amazing_marvin_mcp/

# Use the release script to bump version and create tag
python scripts/release.py patch   # for bug fixes
python scripts/release.py minor   # for new features
python scripts/release.py major   # for breaking changes

# Push to trigger CI and PyPI publish
git push origin main
git push origin v1.x.x

The workflow:

1. ✅ Tests run on Python 3.8-3.12
2. ✅ Linting and type checking pass
3. 📦 Package is built and checked
4. 🚀 Published to PyPI automatically on version tags

🔧 Local Development Setup

git clone https://github.com/bgheneti/Amazing-Marvin-MCP.git
cd Amazing-Marvin-MCP
pip install -e ".[dev]"
pre-commit install

🧪 Testing

You can also manually publish to Test PyPI by running the workflow manually on GitHub.

🔒 Privacy & Security

🛡️ Your Data Protection

• Local Processing: MCP runs entirely on your machine
• Direct Connection: Data goes directly from Amazing Marvin to your AI
• No Cloud Storage: Nothing is stored on external servers
• API Key Security: Store your key securely using environment variables

🔐 Best Practices

• ✅ Use environment variables for API keys (not config files)
• ✅ Don't share your API key in screenshots or logs
• ✅ Keep your API key secure and treat it like a password

⚖️ Performance & Limitations

What to expect:

• Your AI assistant fetches fresh data from Amazing Marvin when you ask questions
• Historical data is cached briefly to avoid repeated requests
• Response time depends on your internet connection to Amazing Marvin
• Very frequent requests might occasionally hit rate limits (just wait a moment)

Technical details:

• Data is fetched in real-time for accuracy
• Some data is cached for 10 minutes to improve speed
• Batch operations work efficiently for multiple tasks
• All the core Amazing Marvin features are supported

📄 License

MIT License - see LICENSE for details.