@chukaofili/next-mcp

A Model Context Protocol (MCP) server for scaffolding production-ready Next.js applications with Docker support, authentication, database integration, and more.

Features

• Automated Next.js Setup: Generate complete Next.js projects with TypeScript, React Compiler, and modern tooling
• Database Integration: Support for PostgreSQL, MySQL, MongoDB, and SQLite with Prisma, Drizzle, or Mongoose
• Authentication: Pre-configured better-auth integration with user management
• UI Components: Automatic shadcn/ui setup with all components
• State Management: Optional Zustand or Redux integration
• Testing: Built-in support for Vitest, Jest, or Playwright
• Docker Support: Production-ready Dockerfile and docker-compose.yml generation

Installation

Prerequisites

• Node.js >= 24
• pnpm >= 10 (or npm/yarn/bun)

Claude CLI

Run the following command to add next-mcp as an MCP server:

claude mcp add --transport stdio --scope user next-mcp -- npx @chukaofili/next-mcp@latest

Google Gemini CLI

Run the following command to add next-mcp as an MCP server:

gemini mcp add --transport stdio --scope user next-mcp npx @chukaofili/next-mcp@latest

Cursor IDE

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

{
  "mcpServers": {
    "next-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["@chukaofili/next-mcp@latest"]
    }
  }
}

Available Tools

scaffold_project

Create a complete Next.js project with your specified configuration.

Key Configuration Options:

• typescript (default: true): Enable TypeScript
• database: none, postgres, mysql, mongodb, sqlite
• orm: none, prisma, drizzle, mongoose
• auth: none, better-auth
• uiLibrary: none, shadcn
• stateManagement: none, zustand, redux
• testing: none, jest, vitest, playwright
• packageManager: npm, pnpm, yarn, bun

Example:

{
  "config": {
    "name": "my-awesome-app",
    "architecture": {
      "typescript": true,
      "database": "postgres",
      "orm": "prisma",
      "auth": "better-auth",
      "uiLibrary": "shadcn",
      "stateManagement": "zustand",
      "testing": "vitest"
    }
  },
  "targetPath": "/path/to/projects"
}

Other Tools

• generate_dockerfile: Generate production-ready Docker configuration
• setup_shadcn: Initialize shadcn/ui with all components
• generate_base_components: Generate essential React components and layouts
• setup_database: Configure database connection and migrations
• setup_authentication: Configure better-auth with login/signup pages
• validate_project: Run comprehensive validation checks
• generate_readme: Generate comprehensive project documentation

Example Workflow

1. Create the project:

   "Use next-mcp to scaffold a new Next.js project called 'my-app' with PostgreSQL, Prisma, and better-auth"

2. Add Docker support:

   "Generate Dockerfile and docker-compose.yml for the project"

3. Set up UI components:

   "Initialize shadcn/ui and generate base components"

Development

Build and Test

# Build
pnpm build

# Run tests
pnpm test

# Run with MCP Inspector
pnpm inspector

# Lint and format
pnpm lint
pnpm format

Project Structure

next-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   └── templates/            # Project templates
│       ├── auth/
│       ├── database/
│       └── docker/
├── tests/
│   ├── unit/
│   └── integration/
└── dist/                     # Compiled output

Environment Variables

After scaffolding, configure these in your project's .env:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/dbname"

# Authentication
BETTER_AUTH_SECRET="your-secret-key-here"
BETTER_AUTH_URL="http://localhost:3000"

# Application
NEXT_PUBLIC_APP_URL="http://localhost:3000"

Troubleshooting

Logs

All logs are stored in ~/.next-mcp/:

# View production logs
tail -f ~/.next-mcp/next-mcp.log

# View test logs
tail -f ~/.next-mcp/next-mcp-test.log

MCP Connection Issues

1. Check your Claude Desktop configuration syntax
2. Verify the project is built (pnpm build if running locally)
3. Ensure Node.js >= 24 is installed
4. Check logs in ~/.next-mcp/next-mcp.log

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Ensure all tests pass
5. Submit a Pull Request

Links

• GitHub Repository
• Issue Tracker
• Model Context Protocol
• Next.js Documentation
• shadcn/ui

Made with ❤️ for the Next.js community