mcp-starter-kit

MCP Starter Kit

Create MCP applications with authentication, database, and billing in seconds!

A universal starter kit for building Model Context Protocol (MCP) applications with built-in authentication (Kinde), database (Neon PostgreSQL), and billing systems (Kinde). Perfect for developers who want to start building MCP servers with Cursor.

Features

• Built-in Authentication - Kinde OAuth integration
• Database Ready - Neon PostgreSQL with automatic schema setup
• Billing System - Freemium model with upgrade flows
• Multiple Templates - Blog, E-commerce, CRM, Todo applications
• One Command Setup - Interactive CLI for instant project creation
• Complete Stack - Authentication server + MCP server + Database
• Cursor Integration - Ready to use with Cursor AI

Perfect For

• Developers building MCP servers with Cursor
• Teams creating CRUD MCP servers with authentication and billing
• Anyone who wants to an easy startkerkit setup

Quick Start

# Create a new MCP application (one command!)
npx mcp-starter-kit

This will create your project and guide you through the setup process.

Note: Ignore the npm i mcp-starter-kit command shown on the npm package page. Use npx mcp-starter-kit instead for the best experience.

Available Templates

Template	Description	Entities	Perfect For
blog	Blog management system	posts, comments	Content creators, writers
ecommerce	E-commerce platform	products, orders, order_items	Online stores, marketplaces
crm	Customer relationship management	contacts, deals, tasks	Sales teams, businesses
todo	Simple todo system	todos	Personal productivity, task management

Complete Setup Guide

Step 1: Create Your Application

npx mcp-starter-kit

What you'll see:

🚀 MCP Starter Kit
Create MCP applications with authentication, database, and billing

📝 What would you like to name your application? my-blog
📋 Choose your template:
  1. blog      - Blog management system (posts, comments)
  2. ecommerce - E-commerce system (products, orders)
  3. crm       - Customer relationship management (contacts, deals, tasks)
  4. todo      - Simple todo management system

🎯 Enter your choice (1-4): 1
🚀 Creating my-blog with blog template...
✅ Application created successfully!

Step 2: Install Dependencies

npm install

Step 3: Configure Environment

# Copy environment template
cp .env.example .env

Configure your .env file:

# Database (Get from Neon)
DATABASE_URL=postgresql://username:password@host:port/database

# Kinde Authentication (Get from Kinde)
KINDE_ISSUER_URL=https://your-domain.kinde.com
KINDE_CLIENT_ID=your_client_id
KINDE_CLIENT_SECRET=your_client_secret

# JWT Configuration
JWT_SECRET=your_jwt_secret_key

# Server Configuration
NODE_ENV=development

Step 4: Setup Database

# Create database schema
npm run setup-db

Step 5: Start Authentication Server

# In a separate terminal
npm run auth-server

Visit http://localhost:3000 to login and get your authentication token.

Step 6: Start MCP Server

# In another terminal
npm run dev

Step 7: Configure Cursor

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

{
  "mcpServers": {
    "my-blog": {
      "command": "node",
      "args": ["dist/universal-server.js"],
      "cwd": "/path/to/your/my-blog",
      "env": {
        "DATABASE_URL": "your_database_url",
        "KINDE_ISSUER_URL": "your_kinde_issuer_url",
        "KINDE_CLIENT_ID": "your_kinde_client_id",
        "KINDE_CLIENT_SECRET": "your_kinde_client_secret",
        "JWT_SECRET": "your_jwt_secret"
      }
    }
  }
}

Authentication Flow

• Start Auth Server - npm run auth-server
• Visit Login Page - http://localhost:3000
• Login with Kinde - Complete OAuth flow
• Copy ID Token - From the auth page
• Use in Cursor - Use save_token tool with your token
• Start Building - Use MCP tools in Cursor chat

Available MCP Tools

After authentication, you'll have access to:

• Authentication Tools

  • login - Get authentication URL
  • save_token - Save your authentication token
  • logout - Log out current user
  • refresh_billing_status - Check billing status

• CRUD Tools (based on your template)

  • create_[entity] - Create new items
  • list_[entity]s - List all items
  • get_[entity] - Get specific item
  • update_[entity] - Update existing item
  • delete_[entity] - Delete item

Billing System

• Free Tier - Limited items (configurable per template)
• Upgrade Flow - Automatic redirect to Kinde billing portal
• Usage Tracking - Automatic tracking of free tier usage
• Plan Management - Check current plan and usage

Project Structure

my-blog/
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── .env.example              # Environment template
├── README.md                 # Project documentation
└── src/
    ├── app-config.ts         # Application configuration
    ├── universal-server.ts   # Main MCP server
    ├── setup-db.ts          # Database setup script
    ├── kinde-auth-server.ts  # Authentication server
    └── core/                 # Core MCP modules
        ├── auth/             # Authentication manager
        ├── database/         # Database manager
        ├── server/           # MCP server core
        └── tools/            # Tool factory

Troubleshooting

Common Issues

MCP Server Not Detected in Cursor:

• Check ~/.cursor/mcp.json syntax
• Verify environment variables
• Restart Cursor
• Check server is running

Authentication Issues:

• Verify Kinde credentials
• Check redirect URLs in Kinde dashboard
• Ensure auth server is running on port 3000

Database Connection Issues:

• Verify Neon database URL
• Check database permissions
• Run npm run setup-db to create schema

Getting Help

• Check the generated README in your project
• Verify all environment variables are set
• Ensure both servers are running
• Check Cursor MCP configuration

Why Choose This?

• Fast Setup - From zero to working MCP app in minutes
• Production Ready - Real authentication and database
• Billing Ready - Built-in freemium model
• Multiple Templates - Choose what fits your needs
• Complete Stack - Everything you need included
• Cursor Optimized - Perfect for AI development

What's Next?

• Create your first app - npx mcp-starter-kit
• Choose your template - Blog, E-commerce, CRM, or Todo
• Configure your services - Neon database + Kinde authentication
• Start building - Use MCP tools in Cursor
• Deploy and scale - Your app is ready for production

📄 License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please read our contributing guidelines.

Ready to build your first MCP application? Run npx mcp-starter-kit and start building!