nestjs-devtools-mcp

Model Context Protocol (MCP) server for NestJS applications. Exposes runtime logs, routes, request history, errors, and configuration to MCP-compatible AI clients over STDIO.

Architecture

AI Client (Cursor / Claude / etc.)
              │
              │  MCP (STDIO)
              ▼
    nestjs-devtools-mcp (Bridge)
              │
              │  HTTP (localhost)
              ▼
   NestJS App (Preload Hook)

The bridge communicates with the AI client via STDIO and queries the running NestJS application over localhost HTTP.

Related MCP server: Logseq MCP Server

Setup

1. Configure MCP Client

Add the following configuration to your AI client (Cursor, Claude Desktop, Windsurf, Cline, etc.):

{
  "mcpServers": {
    "nestjs-devtools": {
      "command": "npx",
      "args": ["-y", "nestjs-devtools-mcp@latest"]
    }
  }
}

Where to add this:

• Cursor: In ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-level)

• Claude Desktop: In claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

• Claude Code CLI (alternative to manual JSON editing):

  claude mcp add nestjs-devtools -- npx -y nestjs-devtools-mcp@latest

2. Enable in Your NestJS Project

Open a terminal, navigate (cd) into your NestJS project folder (the folder containing package.json), and run:

cd /path/to/my-nestjs-app
npx nestjs-devtools-mcp init

This appends NODE_OPTIONS="--require nestjs-devtools-mcp/register" to .env.local and adds .env.local to .gitignore. No TypeScript source files are modified.

Alternatively, run on demand without creating any configuration files:

npx nestjs-devtools-mcp run -- npm run start:dev

3. Start the Application

In your NestJS project folder, start the development server as usual:

npm run start:dev

The preload hook attaches during startup, enables log buffering, and exposes local inspection endpoints on localhost.

4. Query via AI Client

Your AI client can now query runtime state using the available MCP tools.

Example queries:

• List registered routes, HTTP methods, and controllers.

• Retrieve recent runtime errors or unhandled rejections.

• Inspect failed HTTP requests, status codes, and latencies.

• Check current environment variables and configuration.

Tools

Security

• Localhost only: Endpoints check socket.remoteAddress and reject non-localhost requests.

• Disabled in production: The preload hook does not activate when NODE_ENV=production.

• Secret masking: Values matching credential patterns (passwords, tokens, database URLs, auth headers, private keys) are replaced with ***MASKED***.

Development

pnpm install
pnpm build
pnpm test
pnpm ci

License

MIT © HaoNgo232