Skip to main content
Glama

Todo MCP Server

by sholajegede
npmGitHub
TypeScript
MIT License
1
1
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Modern Todo MCP Server with Authentication, Database & Billing

A complete Model Context Protocol (MCP) server that demonstrates modern web development practices with authentication, billing, and database integration. Perfect for beginners learning full-stack development!

What This Project Does

This project creates a Todo Management System that you can interact with through Cursor AI (or any MCP-compatible client). It includes:

  • Real Authentication with Kinde

  • Billing System with free tier limits

  • Database Storage with Neon PostgreSQL

  • AI Integration through MCP protocol

  • Web Interface for authentication

Key Features

  • 5 Free Todos for new users

  • Upgrade to Paid for unlimited todos

  • Real Authentication with Google/social login

  • Database Persistence with PostgreSQL

  • AI Chat Integration through Cursor

  • Session Management with secure cookies

Architecture Overview

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Cursor AI │ │ MCP Server │ │ Kinde Auth │ │ (Your Chat) │◄──►│ (This Project) │◄──►│ (Authentication)│ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ ▼ ┌──────────────────┐ │ Neon Database │ │ (PostgreSQL) │ └──────────────────┘

Prerequisites

Before you start, you'll need:

  1. Node.js (version 18 or higher)

  2. A Neon Database account (free)

  3. A Kinde account (free)

  4. Cursor IDE (for MCP integration)

Quick Start Guide

Step 1: Clone and Install

# Clone the repository git clone <your-repo-url> cd todo-mcp-server # Install dependencies npm install

Step 2: Set Up Environment

# Run the setup script chmod +x setup.sh ./setup.sh

This creates a .env file with placeholder values.

Step 3: Set Up Neon Database (Free)

  1. Go to neon.tech

  2. Create a free account

  3. Create a new database

  4. Copy your connection string

  5. Update your .env file:

DATABASE_URL=postgresql://your-connection-string-here

Step 4: Set Up Kinde Authentication (Free)

  1. Go to kinde.com

  2. Create a free account

  3. Create a new application

  4. Copy your credentials

  5. Update your .env file:

KINDE_ISSUER_URL=https://your-domain.kinde.com KINDE_CLIENT_ID=your_client_id KINDE_CLIENT_SECRET=your_client_secret

Step 5: Initialize Database

# Set up database tables npm run setup-db

Step 6: Build and Run

# Build the project npm run build # Start the MCP server npm start

Project Structure

mcp-todo-rebuild/ ├── src/ │ ├── server.ts # Main MCP server │ ├── kinde-auth-server.ts # Authentication web server │ └── setup-db.ts # Database setup script ├── dist/ # Compiled JavaScript ├── package.json # Dependencies and scripts ├── tsconfig.json # TypeScript configuration ├── .env # Environment variables (create this) └── README.md # This file

How It Works

1. MCP Server (src/server.ts)

  • Handles AI chat commands like "create todo", "list todos"

  • Manages user authentication and billing

  • Connects to database for data persistence

2. Auth Server (src/kinde-auth-server.ts)

  • Provides web interface for login/logout

  • Handles OAuth flow with Kinde

  • Automatically creates user database records

3. Database Setup (src/setup-db.ts)

  • Creates necessary database tables

  • Sets up indexes for performance

  • Initializes user and todo schemas

How to Use

1. Start the Servers

# Terminal 1: Start MCP server npm start # Terminal 2: Start auth server npm run auth-server

2. Configure Cursor

Add this to your Cursor MCP configuration (~/.cursor/mcp.json):

{ "mcpServers": { "todo-mcp-server": { "command": "node", "args": ["dist/server.js"], "cwd": "/path/to/your/project", "env": { "DATABASE_URL": "your_database_url", "KINDE_ISSUER_URL": "your_kinde_issuer", "KINDE_CLIENT_ID": "your_client_id", "KINDE_CLIENT_SECRET": "your_client_secret", "JWT_SECRET": "your_jwt_secret", "NODE_ENV": "development" } } } }

3. Use in Cursor Chat

Once configured, you can use these commands in Cursor:

login # Get authentication URL save_token: <token> # Save your login token list todos # View your todos create todo # Create a new todo update todo # Update an existing todo delete todo # Delete a todo logout # Log out

Authentication Flow

  1. Type "login" in Cursor chat

  2. Click the URL to open authentication page

  3. Login with Google (or other providers)

  4. Copy your token from the success page

  5. Use "save_token" command in Cursor

  6. Start creating todos!

Billing System

  • Free Tier: 5 todos per user

  • Paid Tier: Unlimited todos (upgrade through Kinde portal)

  • Automatic Tracking: System tracks usage automatically

  • Upgrade URL: Provided when limit is reached

Database Schema

Users Table

CREATE TABLE users ( id SERIAL PRIMARY KEY, user_id TEXT UNIQUE NOT NULL, name TEXT, email TEXT, subscription_status TEXT DEFAULT 'free', plan TEXT DEFAULT 'free', free_todos_used INTEGER DEFAULT 0, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );

Todos Table

CREATE TABLE todos ( id SERIAL PRIMARY KEY, user_id TEXT NOT NULL, title TEXT NOT NULL, description TEXT, completed BOOLEAN DEFAULT FALSE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );

Development Commands

# Development npm run dev # Run MCP server in development npm run auth-server # Run auth server in development # Database npm run setup-db # Set up database tables # Production npm run build # Build for production npm start # Run production server

Configuration

Environment Variables

Create a .env file with these variables:

# Database DATABASE_URL=postgresql://user:pass@host:port/db # Kinde Authentication KINDE_ISSUER_URL=https://your-domain.kinde.com KINDE_CLIENT_ID=your_client_id KINDE_CLIENT_SECRET=your_client_secret # Security JWT_SECRET=your_secret_key # Environment NODE_ENV=development

Troubleshooting

Common Issues

  1. "No authentication token found"

    • Make sure you've logged in and saved your token

    • Check that the auth server is running

  2. "Database connection failed"

    • Verify your DATABASE_URL is correct

    • Make sure you've run npm run setup-db

  3. "Kinde authentication failed"

    • Check your Kinde credentials in .env

    • Verify your redirect URLs in Kinde dashboard

  4. "MCP server not found in Cursor"

    • Restart Cursor after updating mcp.json

    • Check that the server is running with npm start

Debug Mode

Run with debug logging:

DEBUG=* npm run dev

Learning Resources

What You'll Learn

  • MCP Protocol: How AI assistants interact with tools

  • OAuth 2.0: Modern authentication flows

  • PostgreSQL: Database design and queries

  • TypeScript: Type-safe JavaScript development

  • Express.js: Web server development

  • Session Management: User state persistence

Key Concepts

  1. Model Context Protocol (MCP): Standard for AI tool integration

  2. OAuth Flow: Secure authentication without passwords

  3. JWT Tokens: Secure user identification

  4. Database Relations: User-todo relationships

  5. Billing Integration: Freemium business models

Next Steps

Once you understand this project, you can:

  1. Add More Features: Categories, due dates, sharing

  2. Improve UI: Better web interface for auth

  3. Add Real Billing: Stripe integration

  4. Deploy: Host on Vercel, Railway, or AWS

  5. Scale: Add caching, load balancing

Contributing

This is a learning project! Feel free to:

  • Report bugs

  • Suggest improvements

  • Add new features

  • Create tutorials

License

MIT License - feel free to use this for learning and projects!

Need Help?

If you get stuck:

  1. Check the troubleshooting section above

  2. Verify all environment variables are set

  3. Make sure all services are running

  4. Check the console for error messages

Remember: This is a learning project designed to teach modern web development concepts. Take your time, experiment, and don't hesitate to explore the code!

Deploy Server
A
security – no known vulnerabilities
-
license - not tested
A
quality - confirmed to work

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

View all tools

A complete todo management system with authentication and billing that enables AI assistants to create, manage, and track todos with user accounts, free tier limits, and database persistence.

  1. What This Project Does
    1. Key Features
      1. Architecture Overview
        1. Prerequisites
          1. Quick Start Guide
            1. Step 1: Clone and Install
            2. Step 2: Set Up Environment
            3. Step 3: Set Up Neon Database (Free)
            4. Step 4: Set Up Kinde Authentication (Free)
            5. Step 5: Initialize Database
            6. Step 6: Build and Run
          2. Project Structure
            1. How It Works
              1. 1. MCP Server (src/server.ts)
              2. 2. Auth Server (src/kinde-auth-server.ts)
              3. 3. Database Setup (src/setup-db.ts)
            2. How to Use
              1. 1. Start the Servers
              2. 2. Configure Cursor
              3. 3. Use in Cursor Chat
            3. Authentication Flow
              1. Billing System
                1. Database Schema
                  1. Users Table
                  2. Todos Table
                2. Development Commands
                  1. Configuration
                    1. Environment Variables
                  2. Troubleshooting
                    1. Common Issues
                    2. Debug Mode
                  3. Learning Resources
                    1. What You'll Learn
                    2. Key Concepts
                  4. Next Steps
                    1. Contributing
                      1. License
                        1. Need Help?

                          New MCP Servers

                          MCP directory API

                          We provide all the information about MCP servers via our MCP API.

                          curl -X GET 'https://glama.ai/api/mcp/v1/servers/sholajegede/todo_mcp_server'

                          If you have feedback or need assistance with the MCP directory API, please join our Discord server