What is Moleculer Mcp

Moleculer-mcp is a Model Context Protocol (MCP) server that exposes Moleculer.js actions as AI tools, enabling seamless interaction between AI agents and Moleculer microservices.

Use cases

Use cases include building AI-driven applications, enabling AI agents to interact with microservices, and transforming existing Moleculer services into accessible AI tools.

How to use

To use moleculer-mcp, clone the repository, install dependencies, and run the server. It can be run locally or deployed using Docker. Ensure that Node.js 18 or later and a NATS server are available.

Key features

Key features include automatic conversion of Moleculer actions to MCP tools, schema mapping to Zod schemas, real-time discovery of Moleculer actions, Express.js integration for HTTP transport, NATS for service communication, and Docker support for deployment.

Where to use

Moleculer-mcp can be used in various fields including AI development, microservices architecture, and any application requiring integration of AI tools with existing services.

Moleculer MCP Bridge

A Model Context Protocol (MCP) server that exposes Moleculer.js actions as AI tools.

📋 Overview

Moleculer-MCP acts as a bridge between the Model Context Protocol (MCP) and Moleculer.js microservices. It automatically exposes all your Moleculer service actions as MCP tools, enabling AI agents to seamlessly interact with your Moleculer services.

🚀 Quick Start

Installation

npm install -g moleculer-mcp

Basic Usage

1. Start with default settings (connects to local NATS and exposes all actions):

   moleculer-mcp start
   

2. Use your existing Moleculer configuration:

   moleculer-mcp start -m ./moleculer.config.js
   

3. Use a custom bridge configuration:

   moleculer-mcp start config.json
   

4. Combine both configurations:

   moleculer-mcp start config.json -m ./moleculer.config.js
   

Configuration

Create a config.json file to customize the bridge behavior:

{
  "allow": [
    "users.*",
    "posts.*",
    "$node.health"
  ],
  "server": {
    "port": 3000
  },
  "tools": [
    {
      "name": "get_user_list",
      "action": "users.list",
      "description": "Get paginated list of users",
      "params": {
        "limit": 50
      }
    }
  ]
}

Configuration Options:

• allow: Array of action patterns to expose (supports wildcards like "users.*")
• server.port: Port for the MCP server (default: 3000)
• broker.configFile: Path to your Moleculer config file
• tools: Custom tool definitions with parameter overrides

CLI Commands

# Start the bridge
moleculer-mcp start [config.json] [-m moleculer.config.js]

# List available actions
moleculer-mcp list-actions [-c config.json] [-m moleculer.config.js]

# Validate configuration
moleculer-mcp validate-config config.json

Integration with AI Clients

Once running, your Moleculer actions are available at:

• http://localhost:3000/ (MCP endpoint)
• http://localhost:3000/v1/mcp (Alternative endpoint)

Configure your AI client (Claude Desktop, etc.) to use this endpoint as an MCP server.

📚 Example

If you have a Moleculer service like this:

// user.service.js
module.exports = {
  name: "users",
  actions: {
    list: {
      params: { limit: "number", offset: "number" },
      handler(ctx) {
        return this.getUsers(ctx.params);
      }
    }
  }
};

The bridge automatically exposes it as an MCP tool that AI agents can call:

{
  "name": "users_list",
  "description": "List operation for the users service",
  "parameters": {
    "limit": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    }
  }
}

🔧 Advanced Usage

Using with Docker

The project includes a production-ready Dockerfile with the latest Node.js LTS version, configurable ports, and support for custom configuration files.

Quick Start with Docker

# Build the image
docker build -t moleculer-mcp .

# Run with default settings (port 3000)
docker run -p 3000:3000 moleculer-mcp

# Run with custom port
docker run -p 8080:8080 -e PORT=8080 moleculer-mcp

# Run with custom settings file
docker run -p 3000:3000 \
  -v $(pwd)/my-settings.json:/app/my-settings.json \
  -e SETTINGS_FILE=/app/my-settings.json \
  moleculer-mcp

Using Docker Compose

# Copy the example environment file
cp .env.example .env

# Start with default configuration
docker-compose up

# Start with custom port (edit .env or use environment variables)
HOST_PORT=8080 CONTAINER_PORT=8080 docker-compose up

# Start with custom settings file
SETTINGS_FILE=/app/my-settings.json docker-compose up

Docker Environment Variables

• PORT: Port inside the container (default: 3000)
• SETTINGS_FILE: Path to custom settings file inside container (optional)

Volume Mounts

You can mount your configuration files:

docker run -p 3000:3000 \
  -v $(pwd)/moleculer.config.js:/app/moleculer.config.js:ro \
  -v $(pwd)/settings.json:/app/settings.json:ro \
  moleculer-mcp

Environment Variables

Set configuration via environment variable:

export MCP_BRIDGE_SETTINGS='{"allow":["*"],"server":{"port":3000}}'
moleculer-mcp start

📖 Documentation

For detailed documentation, API reference, and advanced configuration options, visit our documentation site.

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.