# @aidd-app/mcp
**Official AiDD MCP Web Connector** - ADHD-optimized productivity platform accessible from Claude web, mobile, and desktop.
[](https://opensource.org/licenses/MIT)
[](https://github.com/aidd-app/mcp-server)
## 🌐 Universal Access
Works everywhere Claude works:
- ✅ **Claude.ai** (desktop browsers)
- ✅ **Claude mobile apps** (iOS/Android)
- ✅ **Claude Desktop** (all platforms)
- ✅ **ChatGPT Apps** (with rich UI widgets)
Simply connect via URL - no local installation required.
## Features
### 📝 Notes Management
- List, read, create, **update**, and **delete** notes in your AiDD account
- Full-text search and pagination
- Categorization (work/personal) and tags
- Batch delete support
### ✅ Action Items (AI-Powered)
- **AI Extraction**: Extract action items from notes or text using Google Gemini
- List, read, **update**, and **delete** action items with priority/due dates
- Confidence scoring for each extracted item
- Batch delete support
### 🎯 ADHD-Optimized Tasks
- **AI Task Breakdown**: Convert action items into manageable subtasks
- Automatic time estimates
- Energy level requirements
- Dependency tracking
- Task type classification
- **AI Prioritization**: Smart task scoring
- Urgency × Importance × Energy × ADHD compatibility
- Time-of-day optimization
- Personalized recommendations
- **Full CRUD**: Create, read, **update**, and **delete** tasks
- Batch delete support
### 🚀 Async AI Processing
- AI operations run in background by default for better UX
- No timeout issues for large data sets
- **New**: `check_ai_jobs` tool to monitor job progress in real-time
- Check results with `list_tasks` or `list_action_items`
- Optional `waitForCompletion` parameter for small batches
### ⚡ Auto AI Scoring (New in v4.3.22)
For **paid users (PRO/PREMIUM)**, AI scoring is automatically triggered after task conversion:
- **MCP**: Always auto-scores after conversion
- **Web/iOS**: Auto-scores when converting more than 1 action item
This means your tasks are immediately prioritized without needing a separate scoring step!
### 🖼️ ChatGPT UI Widgets (New in v4.4.0)
Rich interactive widgets for ChatGPT Apps integration:
| Widget | Description |
|--------|-------------|
| **Task Dashboard** | Visual task prioritization with AI scores |
| **Action Items** | AI-extracted items with confidence scores |
| **Energy Selector** | Task selection by energy level |
| **Quick Capture** | Fast task creation form |
| **Dependency Graph** | Visual task dependencies |
| **Focus Mode** | Pomodoro-style timer |
| **AI Scoring** | Score distribution and insights |
Widgets are served as MCP resources with `text/html+skybridge` MIME type for native ChatGPT integration.
### 🔐 Authentication
- Browser-based OAuth (Google, Microsoft, Apple)
- Email/password sign-in
- Automatic token refresh
- Secure cloud storage
### 📱 Integrations
- Google Tasks
- Microsoft To Do
- Trello, Todoist, Notion
- TickTick, Evernote
## Quick Start
**Production URL**: `https://mcp.aidd.app/mcp`
1. Open [claude.ai](https://claude.ai) → Settings
2. Navigate to "Connectors" or "MCP"
3. Click "Add Connector"
4. Enter URL: `https://mcp.aidd.app/mcp`
5. Save
That's it! Now use it:
```
You: connect
Claude: [opens browser for authentication]
You: list my tasks
Claude: [shows your AiDD tasks]
You: score my tasks and tell me what to work on next
Claude: [AI analyzes and prioritizes your tasks]
```
---
## 📚 Realistic Usage Examples
### Example 1: Morning Task Planning with Energy Levels
**Scenario**: You want to plan your workday based on your current energy level.
```
You: "I just woke up and have high energy. What should I work on this morning?"
Claude: [Uses score_tasks with timeOfDay="morning", considerCurrentEnergy=true]
Response:
🎯 Tasks Scored & Prioritized
Top Priority Tasks (Next 2 Hours):
1. Complete quarterly performance reviews (Score: 95/100)
• Urgency: 9/10
• Importance: 9/10
• Energy Match: High ✓
📝 Best tackled now while your focus is sharp
2. Draft project proposal for Q2 (Score: 89/100)
• Urgency: 7/10
• Importance: 9/10
• Time: 45 min
📝 Complex task - ideal for morning energy
🌅 Morning Schedule (High Energy):
• Complete quarterly performance reviews
• Draft project proposal for Q2
• Review architecture decisions
```
### Example 2: Meeting Notes to Action Items
**Scenario**: You just finished a team meeting and have raw notes to process.
```
You: "I just finished a team meeting. Here are my notes:
- John will send the budget report by Friday
- Need to schedule client demo for next week
- Sarah mentioned the API is having issues, investigate
- Book conference room for quarterly planning
- Follow up with marketing on campaign results"
Claude: [Uses extract_action_items with source="text"]
Response:
🔍 Action Items Extracted
Summary:
• Source: provided text
• Extraction mode: adhd-optimized
• Action items found: 5
Extracted Action Items:
1. Follow up on budget report from John
• Priority: high
• Category: work
• Confidence: 92%
• Due: Friday
2. Schedule client demo
• Priority: high
• Category: work
• Confidence: 95%
• Due: Next week
3. Investigate API issues
• Priority: high
• Category: work
• Confidence: 88%
• Tags: technical, bug
4. Book conference room for quarterly planning
• Priority: medium
• Category: work
• Confidence: 90%
5. Follow up with marketing on campaign results
• Priority: medium
• Category: work
• Confidence: 87%
Action items have been saved to your AiDD account.
```
### Example 3: Converting Action Items to ADHD-Friendly Tasks
**Scenario**: You have action items but need them broken down into manageable steps.
```
You: "Convert my action items to tasks with ADHD-optimized breakdown"
Claude: [Uses convert_to_tasks with breakdownMode="adhd-optimized"]
Response:
🚀 AI Conversion Started
Converting 5 action items to ADHD-optimized tasks in the background.
What's happening:
• AI is breaking down action items into manageable tasks
• Tasks are being optimized for ADHD-friendly execution
• Each action item may generate multiple subtasks
✨ Auto AI Scoring: Enabled (PRO subscription detected)
• Your tasks will be automatically prioritized after conversion
Check your results:
⏱️ Check back in 2-3 minutes - use the `list_tasks` tool to see your converted tasks.
💡 Or use `check_ai_jobs` to monitor progress in real-time.
```
### Example 4: Monitoring AI Job Progress
**Scenario**: You started a large conversion and want to check progress.
```
You: "Check the status of my AI jobs"
Claude: [Uses check_ai_jobs]
Response:
📊 AI Jobs (2 active)
⏳ **🔄 Task Conversion**
• ID: `job_abc123`
• Status: processing (75%)
✅ **🎯 Task Scoring**
• ID: `job_def456`
• Status: completed
💡 Tip: Use `check_ai_jobs` with a specific `jobId` to get detailed status.
```
### Example 5: Updating and Deleting Items
**Scenario**: You need to modify or clean up your task list.
```
You: "Mark task abc123 as completed and delete the old action items I'm done with"
Claude: [Uses update_task to mark complete, then delete_action_items]
Response:
✅ Task Updated
Updated task: Complete quarterly report
• ID: abc123
• Status: ✅ Completed
• Updated: 12/02/2025, 5:30 PM
🗑️ Action Items Deleted
Successfully deleted 3 action items.
🔗 Also deleted 5 derived tasks.
```
### Example 6: Weekly Review and Planning
**Scenario**: End of week review to see accomplishments and plan ahead.
```
You: "Help me do a weekly review. Show me what I accomplished and what's pending for next week."
Claude: [Uses list_tasks, list_action_items, then score_tasks]
Response:
📊 Weekly Review
✅ Completed This Week:
• 12 tasks completed
• 8 action items resolved
• Highlights:
- Finished quarterly report (Score: 95)
- Deployed API fix (Score: 88)
- Client presentation delivered (Score: 92)
📋 Pending Action Items (7):
• High Priority: 2
• Medium Priority: 4
• Low Priority: 1
🎯 Next Week's Top Priorities:
1. Prepare board presentation (Score: 94/100)
• Due: Tuesday
• Energy: High required
• Time: 2 hours
2. Complete performance reviews (Score: 91/100)
• Due: Friday
• Energy: Medium
• Time: 45 min each
3. Follow up on vendor contracts (Score: 85/100)
• Due: Wednesday
• Energy: Low
• Time: 30 min
💡 Recommendation: Block Tuesday morning for the board
presentation while your energy is highest.
```
---
## Available Tools
### Notes (5 tools)
| Tool | Description | Type |
|------|-------------|------|
| `list_notes` | Browse notes (sortBy: createdAt/updatedAt/title) | Read |
| `read_note` | Read specific note by ID | Read |
| `create_note` | Create new note with title, content, tags, category | Write |
| `update_note` | Update existing note (title, content, tags, category) | Write |
| `delete_notes` | Delete one or more notes by ID | Destructive |
### Action Items (5 tools)
| Tool | Description | Type |
|------|-------------|------|
| `list_action_items` | Browse action items with sorting | Read |
| `read_action_item` | Read specific action item by ID | Read |
| `extract_action_items` | AI-powered extraction from notes or text | Write |
| `update_action_item` | Update existing action item (title, priority, due date, etc.) | Write |
| `delete_action_items` | Delete action items and their derived tasks | Destructive |
### Tasks (7 tools)
| Tool | Description | Type |
|------|-------------|------|
| `list_tasks` | Browse tasks with AI scores | Read |
| `read_task` | Read specific task by ID | Read |
| `create_task` | Create a new task manually | Write |
| `convert_to_tasks` | Convert action items to ADHD-optimized tasks (async) | Write |
| `score_tasks` | AI-powered task prioritization (async) | Write |
| `update_task` | Update existing task (title, energy, time, completed, etc.) | Write |
| `delete_tasks` | Delete one or more tasks by ID | Destructive |
### AI Jobs (1 tool)
| Tool | Description | Type |
|------|-------------|------|
| `check_ai_jobs` | Monitor AI job progress (extraction, conversion, scoring) | Read |
### Authentication (1 tool)
| Tool | Description | Type |
|------|-------------|------|
| `status` | Check authentication status and account info | Read |
**Total**: 18 tools (9 read-only, 6 write, 3 destructive)
---
## Architecture
```
┌─────────────────┐
│ Claude │ (web/mobile/desktop)
│ User │
└────────┬────────┘
│ HTTPS/SSE
↓
┌─────────────────┐
│ AiDD MCP │ Cloud Run (auto-scale 1-10)
│ Web Connector │ Node.js 20, Express, CORS
└────────┬────────┘
│ REST API
↓
┌─────────────────┐
│ AiDD Backend │ Cloud Run (production HA)
│ - Firestore │ - Notes, Tasks, Action Items
│ - Redis │ - Sessions, Cache
│ - Gemini AI │ - Extraction, Conversion, Scoring
└─────────────────┘
```
### ChatGPT Apps Integration
```
ChatGPT App
└── Connects to MCP Server: https://mcp.aidd.app
├── Discovers tools (list_tasks, score_tasks, etc.)
│ └── Each tool has _meta.ui_template linking to widget
└── Discovers resources
├── aidd://notes (JSON data)
├── aidd://tasks (JSON data)
└── aidd://widgets/* (text/html+skybridge)
└── ChatGPT loads in iframe + injects window.openai
```
| Widget Resource | Tool Mapping |
|-----------------|--------------|
| `aidd://widgets/task-dashboard` | `list_tasks` |
| `aidd://widgets/action-items` | `extract_action_items`, `convert_to_tasks` |
| `aidd://widgets/ai-scoring` | `score_tasks`, `check_ai_jobs` |
| `aidd://widgets/quick-capture` | `create_task` |
### Tech Stack
- **Runtime**: Node.js 20
- **Framework**: Express.js
- **Protocol**: MCP over HTTP/SSE (Streamable HTTP Transport)
- **Transport**: Server-Sent Events
- **Auth**: OAuth 2.0 with PKCE (S256)
- **AI**: Google Gemini 2.5 Pro & 2.5 Flash
---
## Testing the Connector
You can verify the connector is running:
```bash
# Health check
curl https://mcp.aidd.app/health
# MCP endpoint info
curl https://mcp.aidd.app/mcp
# OAuth discovery
curl https://mcp.aidd.app/.well-known/oauth-authorization-server
```
---
## Subscription Tiers
| Tier | AI Scoring | AI Extractions | Task Conversions | Auto-Scoring | Cooldown |
|------|------------|----------------|------------------|--------------|----------|
| **FREE** | 1/month | 3/week | 1/week | ❌ | 5 min |
| **PRO** | 10/day | 200/week | 200/week | ✅ | None |
**PRO Plans**: $4.99/month or $49.99/year (save $10)
Upgrade at: [https://aidd.app/upgrade](https://aidd.app/upgrade)
---
## Security & Privacy
### Authentication & Data Protection
| Feature | Implementation |
|---------|---------------|
| OAuth 2.0 | Authorization Code Flow with PKCE (S256) |
| Token Security | JWT with 30-day expiry, auto-refresh |
| Transport | HTTPS/TLS 1.3 for all communication |
| CORS | Restricted to `claude.ai`, `*.claude.ai`, `*.anthropic.com` |
| Data at Rest | AES-256 encryption (Google Cloud) |
| Rate Limiting | Token bucket algorithm per subscription tier |
| Request Signing | HMAC verification for API calls |
### Compliance
| Standard | Status |
|----------|--------|
| **GDPR** | ✅ Full compliance (EU data protection) |
| **CCPA** | ✅ Full compliance (California privacy) |
| **SOC 2 Type II** | ✅ Certified infrastructure (Google Cloud) |
### Privacy Policy
AiDD processes your notes, tasks, and action items to provide AI-powered productivity features. We take your privacy seriously:
#### What We Collect
- **Account Information**: Email address, authentication tokens
- **Content Data**: Notes, action items, tasks you create or import
- **Usage Data**: Feature usage for improving the service (anonymized)
#### How We Use Your Data
- **AI Processing**: Notes → Action items → Tasks (on-demand only)
- **Storage**: Encrypted in your personal account
- **Analytics**: Anonymized usage patterns (opt-out available)
#### What We DON'T Do
- ❌ **No AI Training**: Your data is NEVER used to train AI models (including Google Gemini)
- ❌ **No Selling**: Your data is NEVER sold to third parties
- ❌ **No Advertising**: No targeted ads based on your content
- ❌ **No Retention**: AI processing is ephemeral, not stored in AI systems
#### Your Rights
- **Access**: Export all your data at any time
- **Deletion**: Request complete data deletion (GDPR Article 17)
- **Portability**: Download your data in standard formats
- **Correction**: Update or correct your information
- **Objection**: Opt-out of non-essential processing
#### Data Processing Details
| Data Type | Processing | Retention | AI Involvement |
|-----------|------------|-----------|----------------|
| Notes | Stored encrypted | Until deleted | Extraction only (not stored in AI) |
| Action Items | Generated by AI | Until deleted | Created by Gemini, stored in your account |
| Tasks | AI-scored | Until deleted | Scores calculated on-demand |
| Auth Tokens | OAuth 2.0 | 30 days | None |
| Passwords | NOT stored | N/A | None (OAuth only) |
#### Security Measures
- 🔐 End-to-end encryption for sensitive data
- 🔒 Secrets management via Google Secret Manager
- 🛡️ DDoS protection via Cloud Armor
- 📝 Audit logging with 30-day retention
- 🔍 Regular security audits and penetration testing
**📋 Full Privacy Policy**: [https://aidd.app/privacy](https://aidd.app/privacy)
**📜 Terms of Service**: [https://aidd.app/terms](https://aidd.app/terms)
---
## For Anthropic Reviewers
### Test Account
A dedicated test account is available for Anthropic MCP review:
| Field | Value |
|-------|-------|
| Email | `[TEST_EMAIL_REDACTED]` |
| Password | `[REDACTED]` |
| Subscription | PREMIUM (unlimited) |
| Status | ✅ Active |
**Full testing instructions**: [TEST_CREDENTIALS.md](TEST_CREDENTIALS.md)
### Pre-loaded Test Data
- **16 Notes** - Various categories and tags
- **13 Action Items** - Mixed priorities with confidence scores
- **13 Tasks** - All with AI scores (relevance, impact, urgency)
### Support During Review
- **Email**: marc@aidd.app
- **Subject**: "Anthropic MCP Review - [Issue]"
- **Response Time**: < 2 hours (9am-6pm PST)
---
## Troubleshooting
### "Connection Failed"
1. Check health: `curl https://mcp.aidd.app/health`
2. Verify URL: `https://mcp.aidd.app/mcp`
3. Try removing and re-adding the connector
### "Authentication Error"
1. Browser popup blocked? Allow popups for claude.ai
2. Try incognito mode (clear cookies)
3. Check if test account credentials are correct
### "Rate Limit Exceeded"
- Check quota with `status` tool
- Upgrade at [https://aidd.app/upgrade](https://aidd.app/upgrade)
---
## Why Web Connector?
**vs Desktop Extension:**
| Feature | Desktop | Web Connector |
|---------|---------|---------------|
| Platforms | macOS/Windows/Linux only | All platforms |
| Installation | Local install required | Just add URL |
| Updates | Manual | Automatic |
| Mobile | ❌ | ✅ |
**vs Separate MCPs:**
- Combine AiDD with other MCP connectors
- Example: Use with [Apple Notes MCP](https://github.com/gongrzhe/claude-apple-notes-mcp) for macOS
- Claude orchestrates between multiple MCPs automatically
---
## Support
- 🌐 Website: [aidd.app](https://aidd.app)
- 📧 Email: support@aidd.app
- 🐛 Issues: [GitHub](https://github.com/aidd-app/mcp-server/issues)
- 📚 Docs: [docs.aidd.app](https://docs.aidd.app)
## Contributing
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md)
## License
MIT © AiDD Team
---
## Changelog
### v4.4.0 (2025-12-19)
- 🖼️ **New**: ChatGPT UI Widgets - Rich interactive components for ChatGPT Apps
- Task Priority Dashboard with AI scores
- Action Item Extraction Preview with confidence
- Energy-Based Task Selector
- Quick Capture Form
- Dependency Graph visualization
- Focus Mode timer
- AI Scoring Results Card
- 📦 **New**: MCP Resources for UI widgets (`aidd://widgets/*`)
- Self-contained HTML with inlined CSS/JS
- `text/html+skybridge` MIME type for ChatGPT integration
- Tool-to-widget linking via `_meta.ui_template`
- 🔧 **Architecture**: UI bundled directly into MCP server
- No separate hosting required
- Automatic discovery by ChatGPT Apps
- 📊 **Total tools**: 18 (unchanged) + 8 widget resources
### v4.3.22 (2025-12-02)
- 🔍 **New Tool**: `check_ai_jobs` - Monitor AI job progress in real-time
- Check specific job by ID or list all active jobs
- Shows job type, status, progress percentage, and timestamps
- Provides helpful next steps based on job status
- ⚡ **Auto AI Scoring**: Paid users (PRO/PREMIUM) now get automatic task scoring after conversion
- MCP: Always auto-scores after task conversion
- Web/iOS: Auto-scores when converting more than 1 action item
- No separate scoring step needed - tasks are prioritized automatically
- 📊 **Total tools**: 17 → 18
### v4.3.18 (2025-11-30)
- 🔗 **Cascade Delete**: `delete_action_items` now automatically deletes all tasks derived from those action items
- Prevents orphaned tasks when cleaning up action items
- Response shows count of both deleted action items and derived tasks
### v4.3.7 (2025-11-28)
- 🔒 **Security**: Added MCP safety annotations to all 20 tools
- `readOnlyHint: true` for read-only operations (list_*, read_*, status)
- `destructiveHint: true` for delete operations (delete_notes, delete_action_items, delete_tasks)
- `readOnlyHint: false, destructiveHint: false` for write operations
- 🔐 **OAuth**: Added Claude callback URLs to allowlist (localhost:6274, claude.ai, claude.com)
- 🌐 **HEAD**: Added HEAD request handlers for OAuth endpoints
### v4.1.1 (2025-11-25)
- ✏️ **New**: `update_note` - Update existing notes (title, content, tags, category)
- 🗑️ **New**: `delete_notes` - Delete one or more notes (batch support)
- ✏️ **New**: `update_action_item` - Update action items (title, priority, due date, completed status)
- 🗑️ **New**: `delete_action_items` - Delete one or more action items (batch support)
- ✏️ **New**: `update_task` - Update tasks (title, energy, time, type, completed status)
- 🗑️ **New**: `delete_tasks` - Delete one or more tasks (batch support)
- 📊 **Total tools**: 11 → 17
### v4.1.0 (2025-11-24)
- 🚀 **New**: Async mode for AI operations (default)
- ⚡ **Improved**: `convert_to_tasks` runs in background, no timeout issues
- ⚡ **Improved**: `score_tasks` runs in background, handles large task lists
- 🔧 **New**: `waitForCompletion` parameter for synchronous mode
- 📝 **Improved**: Better response messages with "check in 2-3 minutes" guidance
### v4.0.2 (2025-11-24)
- 📚 **Docs**: Added 5 realistic usage examples for Anthropic review
- 🔒 **Privacy**: Enhanced privacy policy section with full details inline
- 🐛 **Fix**: AI scores display (relevance, impact, urgency)
- 🐛 **Fix**: Task scoring deviceId requirement
### v4.0.0 (2025-01-22) - Web Connector Edition
- 🌐 **Breaking**: Transitioned from stdio to HTTP/SSE transport
- 📱 **New**: Universal access (web, mobile, desktop)
- ☁️ **New**: Hosted service with auto-scaling
- 🔒 **Enhanced**: CORS for Claude domains
- ❌ **Removed**: Apple Notes integration (use separate MCP)
- ⚡ **Improved**: Cloud-native observability
### v3.0.0 (2025-01-15)
- CRUD-based architecture
- 11 comprehensive tools
- Direct backend integration
- Enhanced AI features
### v2.0.0 (2025-01-10)
- Browser-based OAuth
- Multi-provider sign-in
### v1.0.0 (2025-01-05)
- Initial release
---
**Made with ❤️ by the AiDD Team for the ADHD community**
*Transform your notes into actionable tasks, from anywhere, on any device.*
