Amazing Marvin MCP Server
🌐 Hosted on Smithery - Install-free access to Amazing Marvin through Claude and other MCP clients
A high-quality Model Context Protocol (MCP) server that connects AI assistants to Amazing Marvin, the powerful task management and productivity system. Built with FastMCP and deployed on Smithery for hosted, zero-installation access.
✨ What's New in v2.0 (Smithery)
Complete migration to Smithery for hosted deployment:
- 🌐 Hosted Infrastructure: No local installation, Python, or dependencies required
- 🔐 Secure Configuration: API tokens managed through Smithery's session config
- 📊 Usage Monitoring: Track server usage and performance
- 🚀 Auto-deployment: Push to GitHub → Automatic deployment
- 🔄 Auto-scaling: Handle multiple concurrent users
- 💪 Same Power: All 10 tools with identical functionality
Technical improvements:
- FastMCP framework with
@smithery.server()decorator - Pydantic V2 validation with session config schemas
- Context-aware API authentication
- Dual response formats (Markdown/JSON)
- Enhanced error handling with actionable guidance
Quick Start
For Users
-
Get your Amazing Marvin API token
- Visit https://app.amazingmarvin.com/pre?api=
- Copy your
API_TOKEN
-
Connect via Smithery
- Visit: https://smithery.ai/server/amazing-marvin-mcp
- Click "Connect"
- Paste your API token when prompted
- Use in Claude Desktop or other MCP clients
-
Start using
"Show me my tasks for today" "Create a task to review Q4 budget tomorrow" "What categories do I have?"
For Developers
See SMITHERY_DEPLOYMENT.md for deployment guide.
Local testing:
uv venv
uv pip install -r requirements.txt
uv run playground
Features
This MCP server provides 10 powerful tools for Amazing Marvin:
📋 Task Management
- marvin_add_task - Create tasks with full support for scheduling, labels, time estimates, and Amazing Marvin shortcuts
- marvin_get_todays_tasks - View all tasks scheduled for today or a specific date
- marvin_mark_done - Mark tasks as complete (idempotent)
- marvin_get_due_tasks - See all tasks due today or overdue with smart overdue indicators
🗂️ Organization
- marvin_get_categories - List all your projects and categories with IDs
- marvin_get_labels - View all available labels with IDs
- marvin_get_children - Browse tasks within a specific project, category, or unassigned area
⏱️ Time Tracking
- marvin_start_tracking - Start time tracking on a task
- marvin_stop_tracking - Stop the currently running timer
🎨 Response Formats
All list operations support two output formats:
- Markdown (default): Human-readable with headers, emojis, and formatting
- JSON: Structured data for programmatic processing
Usage Examples
Creating Tasks
"Create a task called 'Review Q4 budget' due tomorrow with a 2-hour time estimate"
"Add a task 'Call dentist' with 15 minute estimate and schedule it for Friday"
"Create a task 'Finish presentation slides #Work @urgent ~120 +2024-03-20'"
Amazing Marvin shortcuts in task titles:
#ProjectName- Assign to project@label- Add a label~60- Time estimate (60 minutes)+2024-03-15- Set due date^1- Set priority
Viewing Tasks
"Show me my tasks for today"
"What tasks are due today or overdue?"
"List all tasks in my Personal category"
"Show me tasks for March 15, 2024 in JSON format"
Managing Tasks
"Mark task task_abc123xyz as complete"
"Start tracking time on task task_abc123xyz"
"Stop the timer"
Organizing
"Show me all my categories and projects"
"What labels do I have?"
"List all unassigned tasks"
Technical Details
Architecture
Smithery Deployment:
- Python 3.12+ runtime
- FastMCP framework with
@smithery.server()decorator - Context-aware authentication via
ctx.session_config - HTTP/SSE transport (not STDIO)
Configuration:
class AmazingMarvinConfig(BaseModel):
api_token: str = Field(
...,
description="Your Amazing Marvin API token. Get it from: https://app.amazingmarvin.com/pre?api=",
min_length=10
)
Package Structure:
src/amazing_marvin_mcp/
├── __init__.py # Package initialization
└── server.py # Main server with tools
Key Features
- Pydantic V2 Validation: Robust input validation with detailed constraints
- Agent-Centric Design: Tools optimized for AI workflows, not just API wrappers
- Dual Response Formats: Markdown (human-readable) and JSON (machine-readable)
- Character Limits: Intelligent handling of large responses (25,000 char limit)
- Tool Annotations: Proper hints for read-only, destructive, and idempotent operations
- Comprehensive Docstrings: Detailed documentation with examples for every tool
Error Handling
The server provides actionable error messages:
- 401 Unauthorized: Guides to check API token configuration
- 404 Not Found: Suggests verifying IDs and item existence
- 429 Rate Limit: Advises waiting before retry
- 500 Server Error: Indicates Amazing Marvin service issues
All errors include specific next steps for resolution.
Development
Local Setup
# Clone repository
git clone https://github.com/LucaDeLeo/amazing-marvin-mcp.git
cd amazing-marvin-mcp
# Create virtual environment
uv venv
# Install dependencies
uv pip install -r requirements.txt
Testing
# Use Smithery playground (ngrok port-forwarding)
uv run playground
# Or run in development mode
uv run dev
Building Package
# Build distribution
python -m build
# Verify build
ls dist/
# Should show: amazing_marvin_mcp-2.0.0-py3-none-any.whl and .tar.gz
Deployment
See SMITHERY_DEPLOYMENT.md for complete deployment guide.
Quick deploy:
- Push to GitHub:
git push origin main - Go to https://smithery.ai/new
- Connect repository
- Click "Deploy"
API Reference
This server uses Amazing Marvin's Limited Access API:
- API Documentation: https://github.com/amazingmarvin/MarvinAPI/wiki
- Help Center: https://help.amazingmarvin.com/
- API Base URL:
https://serv.amazingmarvin.com/api
Endpoints used:
GET /api/categories - List all categories/projects
GET /api/labels - List all labels
GET /api/children - Get items in category
GET /api/todayItems - Get scheduled tasks
GET /api/dueItems - Get due/overdue tasks
POST /api/addTask - Create task
POST /api/markDone - Complete task
POST /api/track - Start/stop timer
Security Notes
- API Tokens: Stored encrypted in Smithery's session config, never in code
- HTTPS Only: All communication over TLS 1.2+
- Input Validation: Pydantic models prevent injection attacks
- Limited Access API: Additional security layer vs Full Access
Contributing
Potential future enhancements:
- Document update/delete operations (
/api/doc/update,/api/doc/delete) - Project creation tool (
/api/addProject) - Goals integration (
/api/goals) - Habit tracking (
/api/habits,/api/updateHabit) - Reminders management (
/api/reminder/set) - Time blocks viewing (
/api/todayTimeBlocks) - Tracked item status (
/api/trackedItem) - Reward points system
When adding features, follow the same patterns: Pydantic model → @mcp.tool decorator → ctx: Context parameter → shared utilities → comprehensive docstring.
Support
Server Issues:
- GitHub Issues: https://github.com/LucaDeLeo/amazing-marvin-mcp/issues
Smithery Platform:
- Email: support@smithery.ai
- Discord: https://discord.gg/Afd38S5p9A
Amazing Marvin API:
- Email: support@amazingmarvin.com
License
MIT License - See LICENSE file
Acknowledgments
- Built with FastMCP
- Deployed on Smithery
- Powered by Amazing Marvin
Version: 2.0.0 (Smithery Deployment) Repository: https://github.com/LucaDeLeo/amazing-marvin-mcp Smithery: https://smithery.ai/server/amazing-marvin-mcp