Aidderall MCP Server
The Aidderall MCP Server is a hierarchical task management tool that gives AI assistants a structured way to organize, track, and navigate complex multi-step work with persistent context.
Task Creation
create_new_task– Create an independent top-level task for unrelated work or parallel workstreamsextend_current_task– Add a subtask under the current task to decompose complex work hierarchically
Navigation & Context
get_current_task– Retrieve the currently active/focused taskswitch_focus– Jump to any task by ID, enabling free navigation across the workspacepeek_context– Inspect the parent task and previous sibling without changing focuslist_siblings– List all sibling tasks to understand position in a sequenceget_big_picture– View the entire task hierarchy (including completed tasks) as a living documentget_stack_overview– Get a full JSON structure of all tasks and their relationships
Task Management
complete_current_task– Mark the current task as completed; it remains visible and focus shifts automaticallyupdate_current_task– Modify the notes/body content of the currently focused taskremove_task– Remove any task (and its subtasks) from the active workspaceget_completed_tasks– View a chronological archive of all completed tasks
Session Management
list_sessions– List all persisted sessions with metadataresume_session– Resume a previous session's full task statedelete_session– Delete a stale session
All task state is automatically saved to SQLite on every change, surviving server restarts and crashes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Aidderall MCP Server create a main task for implementing user authentication with subtasks for database, API, and UI"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.

Welcome to Aidderall MCP Server!
Aidderal is a Model Context Protocol (MCP) server implementation for hierarchical task management, providing AI assistants with a cognitive prosthetic for maintaining focus and context across complex problem-solving sessions.
AI assistants have a hard time dealing with long running tasks, in part due to limitations in the amount of information they can handle at any one point in time (context window).
Aidderall solves this issue by giving the AI assistant:
Focus
A map of the current cognitive landscape with context
Think of aidderall as many small context windows which help the AI focus and remember!
Overview
Aidderall implements a flexible hierarchical task management system where:
Tasks can be organized in nested structures for complex work decomposition
Create independent tasks for parallel work streams
Navigate freely between any tasks using switch_focus
Complete tasks in any order that makes sense for your workflow
All tasks remain visible as a living document of your work

Related MCP server: Codebuddy MCP Server
What does Aidderall look like?
Aidderall Visual Representation
================================
1. Basic Structure - Tasks grow vertically, subtasks grow horizontally:
┌─────────────────┐
│ MainTask C │ ← Latest main task
│ [PENDING] │
└─────────────────┘
↑
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MainTask B │ ──→ │ SubTask B.1 │ ──→ │ SubTask B.2 │
│ [COMPLETED] │ │ [COMPLETED] │ │ [CURRENT] ← │ ← YOU ARE HERE
└─────────────────┘ └─────────────────┘ └─────────────────┘
↑
┌─────────────────┐ ┌─────────────────┐
│ MainTask A │ ─→ │ SubTask A.1 │
│ [COMPLETED] │ │ [COMPLETED] │
└─────────────────┘ └─────────────────┘
2. Living Document - Completed tasks remain visible:
Before (traditional todo): After (Aidderall):
┌─────────────────┐ ┌─────────────────┐
│ ☐ Task A │ │ ✓ Task A │ ← Still visible!
│ ☐ Task B │ │ ✓ Task B │ ← Context preserved
│ ☐ Task C │ │ ☐ Task C │
└─────────────────┘ └─────────────────┘
Traditional: Completed = Gone Aidderall: Completed = History
3. Flexible Navigation with switch_focus:
┌─────────────────┐
│ Task D │
│ [PENDING] │ ←────────────┐
└─────────────────┘ │
↑ │ Can jump to any task!
┌─────────────────┐ │
│ Task C │ │
│ [CURRENT] ← │ ←──────┐ │
└─────────────────┘ │ │
↑ │ │
┌─────────────────┐ │ │
│ Task B │ ←──────┘ │
│ [COMPLETED] │ │
└─────────────────┘ │
↑ │
┌─────────────────┐ │
│ Task A │ ←────────────┘
│ [COMPLETED] │
└─────────────────┘
4. Real-world Example - Implementing a Feature:
┌─────────────────────┐
│ Add User Auth │
│ [COMPLETED] │
└─────────────────────┘
↑
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
└───→ │ Design DB Schema │ ──→ │ Create API │ ──→ │ Add UI Forms │
│ [COMPLETED] │ │ [COMPLETED] │ │ [CURRENT] ← │
└──────────────────┘ └──────────────────┘ └──────────────────┘
↑
│ ┌──────────────────┐
└───→ │ Add JWT logic │
│ [COMPLETED] │
└──────────────────┘
5. Value Propositions Visualized:
Traditional Linear Todo: Aidderall Hierarchical:
======================== =========================
☐ Research auth libraries Research Phase
☐ Design database schema │
☐ Create user table ├─→ Auth libraries
☐ Create session table │ └─→ JWT vs Sessions
☐ Implement JWT │
☐ Create login endpoint Design Phase
☐ Create register endpoint │
☐ Add password hashing ├─→ Database Schema
☐ Create login form │ ├─→ User table
☐ Create register form │ └─→ Session table
☐ Add form validation │
Implementation Phase
Problems: │
- No hierarchy ├─→ Backend API
- No context │ ├─→ Login endpoint
- Hard to see relationships │ ├─→ Register endpoint
- Completed = disappeared │ └─→ Password hashing
│
└─→ Frontend UI
├─→ Login form
├─→ Register form
└─→ Validation
Benefits:
✓ Clear hierarchy
✓ Preserved context
✓ Visible relationships
✓ Complete history
6. Zen State - Two Paths:
Path 1: No tasks Path 2: All completed
┌─────────────────┐ ┌─────────────────┐
│ │ │ ✓ Task A │
│ Empty Stack │ │ ✓ Task B │
│ (Zen State) │ │ ✓ Task C │
│ │ │ (Zen State) │
└─────────────────┘ └─────────────────┘Features
Hierarchical Task Management: Create main tasks and extend them with subtasks
Focus Enforcement: Only one task can be active at a time
Context Preservation: Maintain breadcrumb trails and sibling awareness
Task Completion: Archive completed tasks with timestamps
Session Persistence: Task state is automatically persisted to SQLite on every mutation — survives server restarts, crashes, and context compaction
Session Management: Each server instance gets a unique session. List, resume, or clean up previous sessions
Acknowledgements
Thanks to Alberto “KewlPops” Fernandez for coming up with the name... the project name was not so exciting before! 😀
Installation
Clone the repository:
git clone https://github.com/user/aidderall_mcp.git
cd aidderall_mcpCreate and activate a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activateInstall dependencies:
pip install -r requirements.txtFor development, install with dev dependencies:
pip install -e ".[dev]"Usage
Running the Server
Start the MCP server:
python -m src.serverThe server runs via the Python module directly.
Integrating with AI Assistants
For Claude Code
If you have Claude Code installed, you can add Aidderall directly:
claude mcp add aidderall-mcp /path/to/aidderall_mcp/run_mcp.shManual Configuration
Alternatively, add the server to your MCP configuration:
{
"mcpServers": {
"aidderall": {
"command": "python",
"args": ["-m", "src.server"]
}
}
}Available Commands
Task Creation
create_new_task(title, body)- Create a new independent task for unrelated work or new topicsextend_current_task(title, body)- Add a subtask to organize and break down the current task
Navigation & Information
get_current_task()- Returns current task with contextget_big_picture(format='text')- Shows entire task hierarchy (format: 'text' or 'json')get_stack_overview()- Returns JSON structure of systempeek_context(include_body=False)- View parent and sibling contextlist_siblings(include_body=False)- List tasks at current level
Task Management
complete_current_task()- Mark current task as complete (stays visible)update_current_task(body)- Update current task bodyswitch_focus(task_id)- Switch focus to any task by IDremove_task(task_id)- Remove task from structure (preserves in history)get_completed_tasks(order)- View completed task archive
Session Management
list_sessions()- List all persisted sessions with metadata (task count, current task, last modified)resume_session(session_id)- Resume a previous session's task state (empty sessions are auto-cleaned on resume)delete_session(session_id)- Delete a stale session (cannot delete the active session)
Example Workflow
# Start with a root task
create_new_task("Design new feature", "Research and design specs")
# Break it down into subtasks for organization
extend_current_task("Research requirements", "User research needed")
extend_current_task("Interview users", "Conduct user interviews")
extend_current_task("Analyze competitors", "Research competitor solutions")
# Work on tasks in any order using switch_focus
get_big_picture() # See all tasks with their IDs
switch_focus("task-id-for-research") # Jump to research task
complete_current_task() # Complete it when done
# Jump to any other task
switch_focus("task-id-for-interviews") # Work on interviews
# ... do some work ...
switch_focus("task-id-for-competitors") # Switch to competitor analysis
# Create parallel work streams
create_new_task("Write documentation", "Document the new feature")
extend_current_task("API docs", "Write API documentation")
extend_current_task("User guide", "Write user guide")
# Jump between different work streams freely
switch_focus("task-id-for-design") # Back to design work
switch_focus("task-id-for-api-docs") # Jump to documentation
# Complete tasks as they're finished, in any order
complete_current_task() # Completes whatever you're currently focused on
# View all tasks - completed ones remain visible
get_big_picture()
# Output shows:
# Design new feature (pending)
# Research requirements (completed)
# Interview users (pending)
# Analyze competitors (completed)
# Write documentation (pending)
# API docs (completed)
# User guide (pending)
# Clean up workspace by removing completed tasks
remove_task("task-id-for-research") # Removes from view but keeps in historyDevelopment
Running Tests
pytest -vCode Coverage
pytest --cov=src tests/Code Formatting
black src tests
isort src testsType Checking
mypy srcPersistence
Task state is automatically persisted to SQLite at ~/.aidderall/sessions/<session_id>/state.db. Each server instance generates a unique session ID, so concurrent sessions never interfere with each other.
Auto-save: Every mutation (create, extend, complete, update, switch, remove) writes to disk immediately
Auto-restore: Resuming a session loads the full task hierarchy, completed archive, and focus state
Auto-cleanup: Empty sessions are deleted when you resume a different session
Architecture
models.py- Core data structures (Task, MainTask, SubTask) with serializationtask_manager.py- Task management logic and state handlinghandlers.py- MCP command implementationspersistence.py- SQLite-backed session persistenceserver.py- MCP server entry point
Documentation
Usage Guide - Comprehensive guide for getting AI assistants to use Aidderall effectively
Technical Specification - Detailed technical specification of the hybrid stack-list model
AI Assistant Evolution - Vision for transforming AI from stateless oracle to focused worker
Work Log - Development history and architectural decisions
Contributing
Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request
License
This project is licensed under the GNU General Public License v3.0 or later - see the LICENSE file for details.
Copyright (C) 2024 Briam R. briamr@gmail.com
Available Tools
12 toolscomplete_current_taskA
Mark current task as COMPLETED. Task remains visible in structure (living document approach). Focus automatically moves to a nearby incomplete task. Creates permanent record in history. You can use switch_focus to work on any specific task instead. Use remove_task to clean up workspace later.
Inputs: no named parameters.
create_new_taskA
Create an INDEPENDENT task for unrelated work. Use for: new topics, context switches, or parallel workstreams. Adds a new top-level task to your workspace. Previous task keeps its status. Example: working on Feature A, need to research Topic B → create_new_task for Topic B. For breaking down current work, use extend_current_task.
Inputs: title (required), body (required).
extend_current_taskA
Add a subtask to organize and decompose work. Creates hierarchical structure for complex tasks. Subtasks help break down work into manageable pieces. You can work on tasks in any order using switch_focus. Example: Task A → Task B → Task C creates a nested structure, but you can jump between them freely. For unrelated work, use create_new_task.
Inputs: title (required), body (required).
get_big_pictureA
See ALL tasks in your task stack (including completed ones). Shows full work context as a living document. Marks current task with 'YOU ARE HERE'. Indicates zen state when no tasks exist OR all tasks are completed.
Inputs: format.
get_completed_tasksA
View chronological history of ALL completed tasks. This is a permanent archive separate from the visible structure. Tasks remain here even after being removed from the workspace. Useful for reviewing what you've accomplished over time.
Inputs: order.
get_current_taskA
Get the task with CURRENT status (your active focus). May be manually set via switch_focus, or automatically determined. In zen state (no tasks OR all tasks completed), returns appropriate message.
Inputs: no named parameters.
get_stack_overviewB
Get structured data of your entire task stack (JSON format with all task details and relationships)
Inputs: no named parameters.
list_siblingsB
See all sibling tasks to the left of current focus. May include both pending and completed tasks. Helpful for understanding your position in the current task sequence.
Inputs: include_body.
peek_contextA
Look at parent task and previous sibling without changing focus (understand WHY you're doing current task)
Inputs: include_body.
remove_taskA
Remove a task from the structure (cleanup your workspace). The task remains in completed_tasks history if it was completed. Can remove any task (completed or not). Removing a parent task removes all its subtasks. Use get_big_picture or get_stack_overview to see task IDs.
Inputs: task_id (required).
switch_focusA
Switch focus to ANY task by ID. The primary way to navigate your task workspace - jump between tasks in any order, revisit completed work, or change priorities on the fly. Current task retains its status, target task becomes current. Use get_big_picture or get_stack_overview to see task IDs.
Inputs: task_id (required).
update_current_taskB
Update notes/content of the task you're currently focused on (current task only)
Inputs: body (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool has a clearly distinct purpose with no ambiguity. For example, 'complete_current_task' marks a task as completed, 'create_new_task' adds an independent task, and 'extend_current_task' adds a subtask—these are well-differentiated. Tools like 'get_big_picture' and 'get_stack_overview' serve different informational needs (overview vs. structured data), and navigation tools like 'switch_focus' and 'peek_context' have unique roles.
All tool names follow a consistent verb_noun pattern using snake_case, such as 'complete_current_task', 'create_new_task', and 'get_big_picture'. There are no deviations in naming conventions, making the set predictable and easy to understand. This consistency aids in agent comprehension and tool selection.
With 12 tools, the count is well-scoped for a task management server, covering creation, navigation, status updates, and information retrieval without being overwhelming. Each tool serves a specific function in managing tasks, such as 'remove_task' for cleanup and 'list_siblings' for context, ensuring a comprehensive yet manageable toolset.
The toolset provides complete coverage for task management, including CRUD operations (create, update, remove), status changes (complete), navigation (switch_focus, peek_context), and information retrieval (get_current_task, get_big_picture). There are no obvious gaps; agents can handle all aspects of task lifecycle and workspace management without dead ends.
Related MCP Connectors
AI-native task management: list, create, update and archive tasks with rich context for AI agents
Shared task layer for AI agents: tasks, handoffs and decisions that persist across tools.
Task manager for AI agents. Orchestrate agents to achieve large goals in unified control plane.
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
Related MCP Servers
- AlicenseBqualityFmaintenanceEnables AI agents to break down complex tasks into manageable pieces using a structured JSON format with task tracking, context preservation, and progress monitoring capabilities.1522 npm7MIT
- FlicenseNot gradedqualityDmaintenanceA cognitive scaffolding platform that helps AI agents break down complex tasks into manageable steps using hierarchical planning and metacognitive guidance. Provides persistent memory, progress tracking, and intelligent pattern recognition to learn from successful project structures.-
- FlicenseNot gradedqualityDmaintenanceEnables AI development tools to maintain context across chat sessions with automatic branching, progress tracking, and TODO management for different tasks.-
- AlicenseBqualityBmaintenancePut your digital chores on autopilot: Build always-on agents from a single prompt. Give Claude Code goals like "Maintain my repo" and it works on them in the background on a schedule, asks you to approve actions from a pane beside your chat or your phone, and remembers your decisions. Claude Code plugins + MCP server, local SQLite.24142Apache 2.0