nest-mcp

A NestJS library for integrating Model Context Protocol (MCP) server capabilities into existing or new NestJS applications.

Features

• 🚀 Easy Integration — Add MCP server capabilities to any NestJS app with minimal configuration
• 🎯 Decorator-Based API — Use @Prompt, @Resource, and @Tool decorators to expose MCP primitives
• 🔌 Multiple Transports — WebSocket (ws) and Redis pub/sub transports
• 💉 Dependency Injection — Full support for NestJS DI; handlers are discovered automatically via DiscoveryService
• 🛝 Built-in Playground — Interactive UI served at /mcp/playground for testing all registered prompts, resources, and tools
• 📝 TypeScript — Written in strict TypeScript with full type safety

Installation

npm install nest-mcp

Peer Dependencies

npm install @nestjs/common @nestjs/core rxjs reflect-metadata

Node.js ≥ 20.0.0 is required.

Quick Start

1. Import the Module

import { Module } from '@nestjs/common';
import { McpModule } from 'nest-mcp';

@Module({
  imports: [
    McpModule.register({
      transport: 'websocket',
      serverName: 'my-mcp-server',
      serverVersion: '1.0.0',
      websocket: {
        port: 3001,
        host: 'localhost',
      },
    }),
  ],
})
export class AppModule {}

2. Create MCP Handlers

Decorate any @Injectable() provider with @Prompt, @Resource, or @Tool. The library discovers them automatically at startup.

import { Injectable } from '@nestjs/common';
import {
  Prompt,
  PromptParam,
  Resource,
  ResourceParam,
  Tool,
  ToolParam,
} from 'nest-mcp';

@Injectable()
export class McpHandlersService {
  // --- Prompt ---
  @Prompt({ name: 'greeting', description: 'Generates a personalised greeting' })
  greet(
    @PromptParam('name', { description: 'User name', required: true })
    name: string,
  ): string {
    return `Hello, ${name}!`;
  }

  // --- Resource ---
  @Resource({
    uri: 'config://app-settings',
    name: 'Application Settings',
    description: 'Current application configuration',
    mimeType: 'application/json',
  })
  getAppSettings(): string {
    return JSON.stringify({ version: '1.0.0', environment: process.env.NODE_ENV });
  }

  // --- Tool ---
  @Tool({ name: 'add', description: 'Adds two numbers' })
  add(
    @ToolParam('a', { description: 'First number', type: 'number', required: true })
    a: number,
    @ToolParam('b', { description: 'Second number', type: 'number', required: true })
    b: number,
  ): number {
    return a + b;
  }
}

3. Register the Provider

@Module({
  imports: [McpModule.register({ transport: 'websocket', websocket: { port: 3001 } })],
  providers: [McpHandlersService],
})
export class AppModule {}

4. Start Your Application

npm run start

The MCP server is now reachable at ws://localhost:3001 and the playground UI is available at http://localhost:3000/mcp/playground.

---

Configuration

McpModule.register(options)

Synchronous registration.

McpModule.register({
  transport: 'websocket',   // required: 'websocket' | 'redis'
  serverName: 'my-server',  // optional, default: 'nest-mcp-server'
  serverVersion: '1.0.0',   // optional, default: '1.0.0'
  enablePlayground: true,   // optional, default: true
  websocket: {
    port: 3001,             // optional, default: 3001
    host: 'localhost',      // optional, default: 'localhost'
    path: '/mcp',           // optional
  },
});

McpModule.registerAsync(options)

Asynchronous registration — useful with ConfigService or any other async factory.

import { ConfigModule, ConfigService } from '@nestjs/config';

McpModule.registerAsync({
  imports: [ConfigModule],
  useFactory: (configService: ConfigService) => ({
    transport: configService.get<'websocket' | 'redis'>('MCP_TRANSPORT'),
    serverName: configService.get('MCP_SERVER_NAME'),
    websocket: {
      port: configService.get<number>('MCP_WS_PORT'),
    },
  }),
  inject: [ConfigService],
});

registerAsync also accepts useClass and useExisting via the McpModuleOptionsFactory interface.

WebSocket Transport Options

Option	Type	Default	Description
port	number	3001	Port the WebSocket server listens on
host	string	'localhost'	Host to bind to
path	string	—	Optional WebSocket path

Redis Transport Options

Option	Type	Default	Description
host	string	—	Redis host
port	number	—	Redis port
password	string	—	Redis password
db	number	—	Redis database index
channelPrefix	string	—	Prefix for pub/sub channel names

Playground UI

The playground is enabled by default and mounted at /mcp/playground using a raw Express route that bypasses NestJS global prefixes, guards, and middleware. It supports interactive testing of all registered prompts, resources, and tools.

To disable it:

McpModule.register({
  transport: 'websocket',
  enablePlayground: false,
  websocket: { port: 3001 },
});

Note: The playground only works with the default Express HTTP adapter (@nestjs/platform-express). Fastify is not supported.

Using with Helmet

If your NestJS application uses Helmet for security headers (e.g., Content Security Policy), you must configure it to skip CSP for playground routes. The playground sets its own permissive CSP headers.

import helmet from 'helmet';

app.use(
  helmet({
    contentSecurityPolicy: {
      directives: {
        defaultSrc: ["'self'"],
        scriptSrc: ["'self'"],
        styleSrc: ["'self'", "'unsafe-inline'"],
        imgSrc: ["'self'", 'data:'],
      },
      // Skip CSP for playground routes - they have their own CSP
      skip: (req) => req.path.startsWith('/mcp/playground'),
    },
  }),
);

This ensures:

• ✅ Playground routes use permissive CSP for full functionality
• ✅ All other routes remain protected by Helmet's security headers
• ✅ No CSP conflicts or console errors

---

API Reference

Decorators

@Prompt(options: PromptOptions)

Marks a method as an MCP prompt handler.

Option	Type	Required	Description
name	string	✅	Unique prompt name
description	string	—	Human-readable description

@PromptParam(name: string, options?: PromptParamOptions)

Decorates a parameter within a @Prompt method.

Option	Type	Default	Description
description	string	—	Parameter description
required	boolean	true	Whether the parameter is required

@Resource(options: ResourceOptions)

Marks a method as an MCP resource handler.

Option	Type	Required	Description
uri	string	✅	Unique resource URI (e.g. config://settings)
name	string	—	Resource display name
description	string	—	Human-readable description
mimeType	string	—	MIME type of the returned content

@ResourceParam(name: string, options?: ResourceParamOptions)

Decorates a parameter within a @Resource method.

Option	Type	Default	Description
description	string	—	Parameter description
required	boolean	true	Whether the parameter is required

@Tool(options: ToolOptions)

Marks a method as an MCP tool handler.

Option	Type	Required	Description
name	string	✅	Unique tool name
description	string	—	Human-readable description
inputSchema	Record<string, unknown>	—	Custom JSON schema; auto-generated from @ToolParam if omitted

@ToolParam(name: string, options?: ToolParamOptions)

Decorates a parameter within a @Tool method.

Option	Type	Default	Description
description	string	—	Parameter description
type	'string' | 'number' | 'boolean' | 'object' | 'array'	'string'	Parameter type used in the generated JSON schema
required	boolean	true	Whether the parameter is required

McpService

Exported from nest-mcp and injectable in any provider.

Method	Return type	Description
getServer()	Server | undefined	Returns the underlying @modelcontextprotocol/sdk Server instance
listPrompts()	{ prompts: PromptInfo[] }	Lists all registered prompts with their argument schemas
listResources()	{ resources: ResourceInfo[] }	Lists all registered resources
listTools()	{ tools: ToolInfo[] }	Lists all registered tools with their input schemas
getPrompt(name, args?)	Promise<{ messages: [...] }>	Executes a prompt handler and returns the MCP message format
readResource(uri, args?)	Promise<{ contents: [...] }>	Reads a resource and returns the MCP contents format
callTool(name, args?)	Promise<{ content: [...] }>	Calls a tool and returns the MCP content format

---

Provider Discovery

The library uses NestJS's DiscoveryService to scan all registered providers at module init. Any @Injectable() class that has methods decorated with @Prompt, @Resource, or @Tool is picked up automatically — there is no manual registration step.

---

MCP Protocol Primitives

Primitive	Decorator	Purpose
Prompt	@Prompt	Templated messages/instructions for an LLM
Resource	@Resource	Data sources the client can read
Tool	@Tool	Functions the client can execute

See the MCP specification for the full protocol details.

---

Development

Build

npm run build

Test

# Run all tests with coverage
npm test

# Watch mode
npm run test:watch

# Coverage report only
npm run test:cov

Lint

# Check
npm run lint

# Auto-fix
npm run lint:fix

Format

# Check
npm run format:check

# Fix
npm run format

API Docs

npm run docs

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md and open a pull request against main.

Commit Convention

This project follows Conventional Commits:

type(scope): subject

Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore

Allowed scopes: module, service, decorator, transport, playground, config, deps, release

---

License

MIT — see LICENSE.

Repository

github.com/hmake98/nest-mcp

Acknowledgments

• Built on NestJS
• Implements Model Context Protocol via @modelcontextprotocol/sdk
• WebSocket transport powered by ws
• Redis transport powered by redis