Amazing Marvin AI Assistant

🚀 Amazing Marvin AI Assistant Integration

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

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

This connects yourAmazing Marvinproductivity 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.

- 🔄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
- Open Amazing Marvin → Settings → API (navigatingheremay be easier on mobile)
- Enable the API and copy your token
- Keep this handy! 🔑

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

Then add to your AI client config (seeinstallation guide)

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

Visit Smithery Registryfor other clients.

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

{ "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" } } } }

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:

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!

Problem: The MCP can't find your API key.
- Verify your API key is correct in Amazing Marvin Settings → API
- Check the environment variable:echo $AMAZING_MARVIN_API_KEY
- Restart your AI client after setting the key
- Ensure no extra spaces in your API key

Problem: Can't connect to Amazing Marvin API.
- Check your internet connection
- Verify Amazing Marvin service status
- Try the connection test:python -c "import requests; print(requests.get('https://serv.amazingmarvin.com/api').status_code)"
- Check if you're behind a corporate firewall

Problem: MCP is running but not returning data.
- Ask explicitly:"Use the Amazing Marvin tool to get my tasks"
- Check if you have any tasks in Amazing Marvin
- Verify API permissions in Amazing Marvin settings
- Restart your AI client

Problem:ModuleNotFoundError: No module named 'amazing_marvin_mcp'
- Reinstall:pip install --force-reinstall amazing-marvin-mcp
- Check Python path:python -c "import sys; print(sys.path)"
- Use full path:which pythonand use that in your config

Absolutely! Your Amazing Marvin data stays between you, Amazing Marvin, and your AI assistant. The connection runs on your computer - nothing is stored on external servers or shared with anyone else.

Any AI assistant that supports the Model Context Protocol, including Claude Desktop, Cursor, VS Code, and Windsurf. More are being added regularly.

- ✅ Your tasks, projects, and categories
- ✅ Due dates, priorities, and completion status
- ✅ Time tracking and goals
- ✅ Labels and organizational structure
- ✅ Productivity history and patterns

Basically everything you see in Amazing Marvin, your AI can see too.

Not noticeably. The system fetches your data from Amazing Marvin when you ask productivity questions. Response time depends on your internet connection, but it's usually very quick.

- ✅ Create new tasks and projects
- ✅ Mark tasks as done
- ✅ Start and stop time tracking
- ✅ Organize tasks in batches

Don't worry - it only makes changes when you specifically ask it to.

Yes! The MCP can find and display completed tasks in several ways:

- ✅ Shows today's completed tasks alongside pending ones
- ✅ Includes completion count and productivity notes
- ✅ Separates completed from pending for clear progress tracking

- ✅ Lists completed vs pending tasks separately
- ✅ Shows completion rate and progress summary
- ✅ Provides detailed task breakdowns

- ✅ Get completed tasks for any specific date (e.g., "June 10th")
- ✅ Flexible time range summaries (1 day, 7 days, 30 days, or custom date ranges)
- ✅Complete task data included- no additional API calls needed for task details
- ✅Smart caching- historical data cached for 10 minutes to avoid redundant calls
- ✅ Project-wise completion analytics with resolved project names
- ✅ Efficient API filtering with cache hit rate tracking
- ✅ Real-time access to completion timestamps and project correlations

- ❌ Delete tasks (requires special API permissions)
- ❌ Delete projects or categories
- ❌ Remove labels or goals
- ❌ Clear time tracking history

- ❌ Modify existing task content (title, notes, due dates)
- ❌ Move tasks between projects
- ❌ Change task priorities or labels
- ❌ Update project settings

- ❌ Full historical completed task archive
- ❌ Detailed time tracking reports (only basic tracking)
- ❌ Private notes or sensitive data
- ❌ Advanced Amazing Marvin features (strategies, rewards setup)

For these operations, use the Amazing Marvin app directly.

Data is fetched in real-time with each request to Amazing Marvin's API. There's no background syncing or caching - you always get the most current data from your Amazing Marvin account.

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

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

AMAZING_MARVIN_API_KEY=your-api-key-here

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

# Run all checks pre-commit run --all-files # Individual tools ruff check . # Linting ruff format . # Formatting mypy . # Type checking pytest tests/ # Tests

The MCP provides 28 comprehensive tools to AI assistants:

- get_daily_productivity_overview()-PRIMARYcomprehensive 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

- 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

- 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

This project uses automated publishing to PyPI via GitHub Actions.

# 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

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

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

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

- 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

- ✅ 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