# Next.js MCP Server

[![CI](https://github.com/kamolc4/nextjs-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/kamolc4/nextjs-mcp-server/actions/workflows/ci.yml)
[![Verified by MCPForge](https://www.mcpforge.tech/api/badge/verified/nextjs-mcp-server)](https://www.mcpforge.tech/verified/nextjs-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```text
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](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

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

cd nextjs-mcp-server

# Install dependencies
npm ci
```

### 2. Configure environment

```bash
cp .env.example .env.local
```

Edit `.env.local`:

```bash
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:

```bash
openssl rand -hex 32
```

### 3. Run locally

```bash
npm run dev
```

The Next.js app starts at:

```text
http://localhost:3000
```

### 4. Check health

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

### 5. List MCP tools

```bash
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:

```bash
npm run build
npm start
```

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

```json
{
  "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:

```json
{
  "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:

```md
[![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

```bash
docker compose up --build
```

### Production build

```bash
npm run build
npm start
```

## Local development commands

```bash
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

```bash
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](LICENSE).