Next.js MCP Server

A production-ready Next.js MCP Server template for the Model Context Protocol.

This template lets Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients inspect a Next.js codebase, analyze App Router and Pages Router structure, discover API routes, and audit build performance through controlled MCP tools.

Built as a starter template for developers and teams that want a secure baseline before adding custom AI-powered development workflows to a Next.js application.

The template follows production engineering practices and can be used as a starting point for enterprise Next.js AI integrations using the Model Context Protocol.

Who this is for

This repository is useful for:

• Next.js developers building AI-assisted development workflows,

• teams that want Claude or Cursor to inspect Next.js projects safely,

• platform engineers building internal MCP tooling,

• agencies creating reusable MCP server templates for client projects,

• developers learning how to host an MCP server inside the Next.js App Router.

Related MCP server: MCP Frontend Analyzer

Features

• Next.js App Router MCP server

• TypeScript-first implementation

• HTTP MCP endpoint at /api/mcp

• Public health endpoint at /api/health

• API key authentication with x-api-key and Authorization: Bearer

• In-memory rate limiting for MCP requests

• Structured Pino logging

• Zod-based environment validation

• MCP tools for Next.js project analysis, API route inspection, and performance audits

• Jest test suite

• GitHub Actions CI workflow

• Docker support

• Claude Desktop and Cursor configuration examples

Architecture

Claude Desktop / Cursor / Windsurf
        │
        │  HTTP POST /api/mcp
        │  x-api-key or Authorization: Bearer <MCP_API_KEY>
        ▼
  Next.js App Router
        │
        ├── app/api/mcp/route.ts
        │     ├── API key validation
        │     ├── rate limiting
        │     └── MCP transport
        │
        ├── app/api/health/route.ts
        │     └── health report
        │
        ▼
  MCP Server
        │
        ├── analyze_nextjs_project
        ├── inspect_api_routes
        └── audit_performance_budget
        │
        ▼
  Local Next.js project filesystem

See the larger diagram in docs/architecture.md.

Source Code

The complete production-ready Next.js MCP Server template is available on GitHub.

Repository:

https://github.com/kamolc4/nextjs-mcp-server

The repository includes:

• Complete TypeScript source code

• Next.js App Router MCP endpoint

• Health checks

• Authentication middleware

• Rate limiting

• MCP tools

• GitHub Actions CI

• Jest test suite

• MIT License

• Claude Desktop and Cursor configuration

• Production deployment examples

Fork the repository or download it as a ZIP to start building immediately.

Available MCP tools

Quick start

1. Clone and install

# Clone repository
git clone https://github.com/kamolc4/nextjs-mcp-server.git

cd nextjs-mcp-server

# Install dependencies
npm ci

2. Configure environment

cp .env.example .env.local

Edit .env.local:

MCP_API_KEY=replace-with-a-long-random-secret
MCP_SERVER_NAME=nextjs-mcp-server
MCP_SERVER_VERSION=1.0.0
NODE_ENV=development
LOG_LEVEL=info
NEXTJS_PROJECT_PATH=/absolute/path/to/your/nextjs/project
ALLOWED_ORIGINS=*
RATE_LIMIT_RPM=60

Generate a strong API key:

openssl rand -hex 32

3. Run locally

npm run dev

The Next.js app starts at:

http://localhost:3000

4. Check health

curl http://localhost:3000/api/health

5. List MCP tools

curl -X POST http://localhost:3000/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'x-api-key: replace-with-your-mcp-api-key' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Connect to Claude Desktop

Build and start the server:

npm run build
npm start

Then add an MCP server entry in your Claude Desktop configuration:

{
  "mcpServers": {
    "nextjs": {
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer replace-with-your-mcp-api-key"
      }
    }
  }
}

Restart Claude Desktop after editing the configuration.

Connect to Cursor

In Cursor, add a new MCP server using the HTTP endpoint:

{
  "name": "nextjs",
  "url": "http://localhost:3000/api/mcp",
  "headers": {
    "Authorization": "Bearer replace-with-your-mcp-api-key"
  }
}

Then restart Cursor or reload the MCP server list.

Configuration

Security notes

This template is safer than a minimal demo, but you should harden it before production use.

Recommended production changes:

• Store MCP_API_KEY in a managed secret manager.

• Rotate MCP_API_KEY regularly.

• Restrict NEXTJS_PROJECT_PATH to the project directory you intend to expose.

• Avoid exposing secrets, .env files, deployment credentials, or private project directories through custom tools.

• Add per-user or per-workspace authorization if multiple users will access the server.

• Add audit logs for every tool call.

• Use HTTPS in production.

• Tune rate limits for your expected load.

• Review every new tool before allowing write access to project files.

Security Review

Verify this server with MCPForge:

https://www.mcpforge.tech/verify

MCPForge can help review:

• exposed tools,

• authentication behavior,

• health checks,

• compatibility with MCP clients,

• risk level of filesystem access,

• security posture before publishing or deployment.

After verification, you can link your public report from this README:

[![Verified by MCPForge](https://www.mcpforge.tech/api/badge/verified/nextjs-mcp-server)](https://www.mcpforge.tech/verified/nextjs-mcp-server)

Read the complete guide on MCPForge:

https://www.mcpforge.tech/blog/next-js-mcp-server

Starter template on MCPForge Code Hub:

https://www.mcpforge.tech/code/next-js-mcp-server-template

Deployment

A common production setup:

1. Deploy this service to Vercel, Railway, Render, Fly.io, AWS, GCP, Azure, or a private Kubernetes cluster.

2. Configure environment variables in the hosting provider.

3. Set MCP_API_KEY to a long random value.

4. Set NEXTJS_PROJECT_PATH to the project path that tools should inspect.

5. Verify /api/health before connecting MCP clients.

6. Verify /api/mcp with a valid API key.

7. Run a public or private verification with MCPForge.

Docker

docker compose up --build

Production build

npm run build
npm start

Local development commands

npm run lint
npm run typecheck
npm test
npm run build

API endpoints

Testing

npm test
npm run test:watch
npm run test:coverage

The test suite covers:

• /api/health response shape,

• missing API key on /api/mcp,

• invalid API key on /api/mcp,

• valid x-api-key authentication,

• valid Authorization: Bearer authentication,

• MCP tools/list,

• config validation defaults,

• rate limit behavior.

Releases

Latest stable release:

v1.0.0

See the Releases page for the full changelog.

Contributing

Contributions are welcome.

If you want to improve this Next.js MCP Server template, open an issue or submit a pull request.

Related MCP Server Templates

Looking for other production-ready MCP Server templates?

• GitHub MCP Server

• Slack MCP Server

• Stripe MCP Server

• Notion MCP Server

• Shopify MCP Server

• HubSpot MCP Server

• PostgreSQL MCP Server

• Linear MCP Server

Browse the complete collection:

https://www.mcpforge.tech/code

License

MIT — see LICENSE.