A modern, hierarchical checklist application with Model Context Protocol (MCP) integration, enabling AI assistants like Claude to directly interact with your checklist data.
Checklist MCP is a full-stack application that combines a beautiful React-based web interface with AI-powered checklist management through the Model Context Protocol. Create, organize, and manage hierarchical task lists while allowing AI assistants to help you stay productive.
- 🌳 Hierarchical Lists: Unlimited nesting levels for complex project structures
- 🤖 AI Integration: Direct integration with Claude and other AI assistants via MCP
- ⚡ Real-time Updates: WebSocket-powered live synchronization across all clients
- 🎨 Modern UI: Beautiful, responsive interface built with React and shadcn/ui
- 📱 Cross-platform: Works on desktop and mobile devices
- 🔧 Developer Friendly: Modular architecture with comprehensive APIs
The application consists of three main components:
┌─────────────────┐ WebSocket ┌──────────────────┐ HTTP API ┌─────────────────┐
│ Web Client │◄─────────────────│ Database Server │◄────────────── │ MCP Server │
│ (React App) │ Real-time UI │ (Express.js) │ REST calls │ (AI Interface) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │
│ │
┌─────────────────┐ │
│ SQLite DB │ │
│ (Data Storage) │ │
└─────────────────┘ │
│
┌─────────────────┐ MCP Protocol │
│ AI Assistant │◄─────────────────────────┘
│ (Claude, etc.) │ stdio/tools
└─────────────────┘
- 🖥️ Web Server (
web_server/): React + TypeScript frontend with modern UI components - 💾 Database Server (
db_server/): Express.js API with SQLite database and WebSocket support - 🤖 MCP Server (
mcp_server/): Model Context Protocol server for AI assistant integration
- Node.js 18+
- npm or yarn
-
Clone the repository:
git clone <repository-url> cd checklist-mcp
-
Install dependencies:
npm run build
Running npm run start will automatically start:
- Database server on
http://localhost:1029 - Web server on
http://localhost:5173 - MCP server (of course)
- Web Interface: http://localhost:5173
- API Documentation: http://localhost:1029
- MCP Server: Available for AI assistant integration
-
Locate your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%/Claude/claude_desktop_config.json
- macOS:
-
Add the MCP server configuration:
{ "mcpServers": { "checklist": { "command": "node", "args": ["/path/to/checklist-mcp/mcp_server/mcp_server.js"], "env": { "DB_SERVER_URL": "http://localhost:1029" } } } } -
Restart Claude Desktop and start using AI-powered checklist management!
Once integrated, you can ask Claude:
- "Show me all my checklists"
- "Create a grocery shopping list with common items"
- "Add subtasks to my 'Website Project' list for planning, design, and development"
- "Mark the first three tasks in my morning routine as completed"
- "Help me organize my project into phases with detailed subtasks"
Claude will automatically use the appropriate tools to manage your checklists.
- Sidebar Navigation: Easy list switching and management
- Hierarchical Tree View: Visual nesting with expand/collapse
- Inline Editing: Click any item to edit text directly
- Drag & Drop: Reorder items and change hierarchy (coming soon)
- Real-time Updates: See changes instantly across all devices
- ✅ Check/Uncheck: Click checkboxes to toggle completion
- ➕ Add Items: Use the "+" button or press Enter after editing
- 📝 Edit Text: Click any item text to edit inline
- 🗑️ Delete Items: Use the delete button in item actions
- 📁 Expand/Collapse: Toggle nested item visibility
checklist-mcp/
├── web_server/ # React + TypeScript frontend
│ ├── src/
│ │ ├── components/ # UI components (shadcn/ui + custom)
│ │ ├── hooks/ # Custom React hooks
│ │ ├── services/ # API communication layer
│ │ ├── store/ # Zustand state management
│ │ └── utils/ # Utility functions
│ └── package.json
├── db_server/ # Express.js API server
│ ├── db_server.js # Main server file
│ ├── migrations/ # Database schema migrations
│ └── package.json
├── mcp_server/ # Model Context Protocol server
│ ├── src/
│ │ ├── tools/ # Individual MCP tool implementations
│ │ ├── config.js # Configuration management
│ │ └── dependency-manager.js # Service orchestration
│ ├── mcp_server.js # Main MCP server
│ └── package.json
└── package.json # Root package with start scripts
Database Server:
cd db_server
npm install
npm start # Runs on http://localhost:1029Web Server:
cd web_server
npm install
npm run dev # Runs on http://localhost:5173MCP Server:
cd mcp_server
npm install
node mcp_server.js # Stdio transport for AI assistants- 🔄 Auto-Dependency Management: MCP server automatically starts required services
- 🔧 Modular Architecture: Clean separation of concerns across all components
- 📡 WebSocket Support: Real-time synchronization between web clients
- 🧪 Comprehensive Testing: Live testing protocols for all MCP tools
- 📝 TypeScript: Full type safety in frontend components
The application uses SQLite with the following core tables:
-- Lists table
CREATE TABLE lists (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- List items table with hierarchical support
CREATE TABLE list_items (
id INTEGER PRIMARY KEY AUTOINCREMENT,
list_id INTEGER NOT NULL,
parent_id INTEGER,
text TEXT NOT NULL,
is_completed BOOLEAN DEFAULT 0,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (list_id) REFERENCES lists(id) ON DELETE CASCADE,
FOREIGN KEY (parent_id) REFERENCES list_items(id) ON DELETE CASCADE
);- GET
/lists- Get all lists - POST
/lists- Create a new list - GET
/lists/:id- Get specific list with items - DELETE
/lists/:id- Delete a list - POST
/lists/:id/items- Add item to list - PUT
/lists/:id/items/:itemId- Update list item - DELETE
/lists/:id/items/:itemId- Delete list item
lists_updated- Broadcast when any list data changes- Connection management - Automatic reconnection and error handling
get_all_lists- Retrieve all checklist listsget_list- Get detailed list with hierarchycreate_list- Create new checklistsadd_list_item- Add items with nesting supportbulk_add_list_items- Add multiple items at oncefind_list_item- Search items by textupdate_list_item- Update text or completion statusdelete_list_item- Delete specific itemsdelete_list- Delete entire lists
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and test thoroughly
- Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- Follow the existing code style and patterns
- Add tests for new functionality
- Update documentation for API changes
- Ensure all services work together correctly
This project is licensed under the MIT License - see the LICENSE file for details.
- Model Context Protocol - The protocol specification
- Claude Desktop - AI assistant with MCP support
- shadcn/ui - UI component library used in the frontend
Built with ❤️ for AI-assisted productivity