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.

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

Tool	Purpose
analyze_nextjs_project	Analyze a Next.js project and return router type, Next.js version, dependencies, scripts, and project metadata.
inspect_api_routes	Scan App Router and Pages Router routes, including API routes and dynamic segments.
audit_performance_budget	Read .next/build-manifest.json after a build and identify heavy pages that exceed a JavaScript budget.

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

Variable	Description	Required
MCP_API_KEY	Shared secret required for /api/mcp. Minimum 16 characters.	Required
MCP_SERVER_NAME	MCP server name exposed to clients.	Optional
MCP_SERVER_VERSION	MCP server version exposed to clients.	Optional
NODE_ENV	Runtime environment: development, production, or test.	Optional
LOG_LEVEL	Pino log level: debug, info, warn, or error.	Optional
NEXTJS_PROJECT_PATH	Project root that MCP tools inspect. Defaults to current working directory.	Optional
ALLOWED_ORIGINS	Reserved for production CORS hardening.	Optional
RATE_LIMIT_RPM	Maximum MCP requests per minute per client.	Optional

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

Method	Path	Description
GET	/api/health	Public health check endpoint.
POST	/api/mcp	MCP endpoint protected by API key authentication.
GET	/api/mcp	MCP endpoint for compatible HTTP transports.

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.