🚀 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
- Open Amazing Marvin → Settings → API
- Enable the API and copy your token
- 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
🖥️ Claude Desktop
Add to your claude_desktop_config.json:
📍 Config file locations:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"amazing-marvin": {
"command": "python",
"args": ["-m", "amazing_marvin_mcp"],
"env": {
"AMAZING_MARVIN_API_KEY": "your-api-key-here"
}
}
}
}
🎯 Cursor
Add to your MCP settings:
{
"mcpServers": {
"amazing-marvin": {
"command": "python",
"args": ["-m", "amazing_marvin_mcp"],
"env": {
"AMAZING_MARVIN_API_KEY": "your-api-key-here"
}
}
}
}
💨 Windsurf
Add to your Windsurf MCP configuration:
{
"mcpServers": {
"amazing-marvin": {
"command": "python",
"args": ["-m", "amazing_marvin_mcp"],
"env": {
"AMAZING_MARVIN_API_KEY": "your-api-key-here"
}
}
}
}
🆚 VS Code
Add to your VS Code MCP configuration:
{
"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:
| What you might ask | Tools the AI will use |
|---|---|
| "What should I focus on today?" | get_daily_productivity_overview() |
| "What tasks do I have today?" | get_daily_productivity_overview() or get_tasks() |
| "Show me my projects" | get_projects() |
| "What's overdue?" | get_due_items() or get_daily_productivity_overview() |
| "Create a new task for X" | create_task() |
| "Mark task Y as done" | mark_task_done() |
| "Start tracking time on this" | start_time_tracking() |
📁 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
"API key not found" error
Problem: The MCP can't find your API key.
Solutions:
- 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
"Connection refused" or timeout errors
Problem: Can't connect to Amazing Marvin API.
Solutions:
- 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
AI says "I don't see any Amazing Marvin data"
Problem: MCP is running but not returning data.
Solutions:
- 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
Python module not found
Problem: ModuleNotFoundError: No module named 'amazing_marvin_mcp'
Solutions:
- 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
❓ Common Questions
Is my data safe?
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.
Which AI assistants work with this?
Any AI assistant that supports the Model Context Protocol, including Claude Desktop, Cursor, VS Code, and Windsurf. More are being added regularly.
What can my AI assistant see?
Your AI can see:
- ✅ 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.
Will this make my AI assistant slower?
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.
Can my AI assistant change my tasks?
Yes, if you ask it to! Your AI can:
- ✅ 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.
Can I see completed tasks?
Yes! The MCP can find and display completed tasks in several ways:
📊 In Daily Focus View:
- ✅ Shows today's completed tasks alongside pending ones
- ✅ Includes completion count and productivity notes
- ✅ Separates completed from pending for clear progress tracking
📁 In Project Overviews:
- ✅ Lists completed vs pending tasks separately
- ✅ Shows completion rate and progress summary
- ✅ Provides detailed task breakdowns
🔍 Efficient Historical Access:
- ✅ 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
What can't the MCP do?
🚫 Cannot Delete or Remove:
- ❌ Delete tasks (requires special API permissions)
- ❌ Delete projects or categories
- ❌ Remove labels or goals
- ❌ Clear time tracking history
📝 Cannot Edit:
- ❌ Modify existing task content (title, notes, due dates)
- ❌ Move tasks between projects
- ❌ Change task priorities or labels
- ❌ Update project settings
📚 Limited Access:
- ❌ 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.
How often is the data updated?
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.
👨💻 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 onlyget_projects()- All projectsget_categories()- All categoriesget_due_items()- Overdue/due items onlyget_child_tasks( parent_id: str, recursive: bool = False )- Subtasks of a parent task/projectget_all_tasks( label: str = None )- Find all tasks with optional label filter (comprehensive search)get_labels()- Task labelsget_goals()- Goals and objectivesget_account_info()- Account detailsget_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 analyticsget_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 tasksmark_task_done( item_id: str, timezone_offset: int = 0 )- Complete taskscreate_project( title: str, project_type: str = "project" )- Create new projectsstart_time_tracking( task_id: str )- Begin time trackingstop_time_tracking( task_id: str )- End time trackingbatch_mark_done( task_ids: list[str] )- Complete multiple tasksbatch_create_tasks( task_list: list[str], project_id: str = None, category_id: str = None )- Create multiple tasksclaim_reward_points( points: int, item_id: str, date: str )- Claim kudos pointsget_kudos_info()- Get reward system and kudos information
🔧 Utility Operations:
test_api_connection()- Verify API connectivityget_project_overview( project_id: str )- Project analyticsget_daily_focus()- Daily prioritiesget_productivity_summary()- Performance metricstime_tracking_summary()- Time analyticsquick_daily_planning()- Planning assistancecreate_project_with_tasks( project_title: str, task_titles: list[str], project_type: str = "project" )- Project setupget_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:
- ✅ 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
🔧 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.
Made with ❤️ for Amazing Marvin users