Puppet Enterprise MCP Server

An MCP (Model Context Protocol) server that exposes the full Puppet Enterprise API to AI assistants. Connect Claude, Cursor, or any MCP-compatible client to manage your Puppet infrastructure through natural language.

Tools (60+)

Orchestrator

Tool	Description
puppet_run	Run Puppet on nodes (enforce or noop)
run_task	Execute a Puppet task on nodes
run_plan	Execute a Puppet plan
stop_job	Stop a running job
stop_plan	Stop a running plan
list_jobs	List orchestrator jobs
get_job	Get job details
get_job_nodes	Get nodes in a job
get_job_report	Get job report
get_job_events	Get job events
list_plan_jobs	List plan jobs
get_plan_job	Get plan job details
get_plan_job_events	Get plan job events
list_tasks	List available tasks
get_task	Get task details
list_plans	List available plans
get_plan	Get plan details
list_scheduled_jobs	List scheduled jobs
delete_scheduled_job	Delete a scheduled job
check_inventory	Check node reachability
get_usage	Get node usage details

Node Classifier

Tool	Description
list_node_groups	List all node groups
get_node_group	Get a node group
create_node_group	Create a node group
update_node_group	Update a node group
delete_node_group	Delete a node group
classify_node	Get classification for a node
list_classes	List known classes
list_environments	List environments
get_node_check_ins	Get node check-in history
update_classes	Refresh class definitions
unpin_nodes	Unpin nodes from all groups

RBAC

Tool	Description
list_users	List all PE users
get_user	Get user details
get_current_user	Get current authenticated user
create_user	Create a local user
update_user	Update a user
delete_user	Delete a user
revoke_user	Revoke user access
reinstate_user	Reinstate a revoked user
list_roles	List RBAC roles
get_role	Get a role
create_role	Create a role
list_user_groups	List user groups
list_permissions	List available permissions
generate_token	Generate an auth token

Code Manager

Tool	Description
deploy_code	Deploy code to environments
get_deploy_status	Check deployment status

PuppetDB

Tool	Description
puppetdb_query	Run a PQL query
list_nodes	List all nodes
get_node	Get node details
get_node_facts	Get node facts
list_facts	List facts
list_reports	List Puppet reports
list_catalogs	List catalogs
get_resources	Query resources
list_fact_names	List all fact names
list_pdb_environments	List PuppetDB environments
get_inventory	Get inventory data

Status

Tool	Description
get_pe_status	PE console services status
get_orchestrator_status	Orchestrator status
get_puppet_server_status	Puppet Server status
get_puppetdb_status	PuppetDB status

Setup

Prerequisites

1. A Puppet Enterprise instance
2. A PE API token (generate via puppet-access login or the RBAC API)
3. Node.js 20+

Environment Variables

Variable	Required	Description
PUPPET_HOST	Yes	PE primary server hostname
PUPPET_TOKEN	Yes	PE API authentication token
PUPPET_CA_CERT	No	CA certificate PEM content
PUPPET_TLS_VERIFY	No	Set true to enforce TLS verification

Install & Build

npm install
npm run build

Run Directly

PUPPET_HOST=puppet.example.com PUPPET_TOKEN=your-token node dist/index.js

Docker

docker build -t puppet-mcp-server .
docker run -e PUPPET_HOST=puppet.example.com -e PUPPET_TOKEN=your-token puppet-mcp-server

MCP Client Configuration

Claude Desktop / Claude Code

Add to your MCP settings:

{
  "mcpServers": {
    "puppet": {
      "command": "node",
      "args": ["/path/to/puppet-mcp/dist/index.js"],
      "env": {
        "PUPPET_HOST": "puppet.example.com",
        "PUPPET_TOKEN": "your-pe-api-token"
      }
    }
  }
}

Hosting for Customers (SSE/Streamable HTTP)

To host this as a remote MCP server over HTTP for multiple customers, wrap the stdio server with a transport adapter. For example using @modelcontextprotocol/sdk's SSEServerTransport or StreamableHTTPServerTransport:

import express from "express";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

// Create per-customer server instances with their own PUPPET_HOST/PUPPET_TOKEN

See the MCP specification for transport options.

Generating a PE API Token

# On the PE primary server:
puppet-access login --lifetime 1y

# Or via the API:
curl -k -X POST https://puppet.example.com:4433/rbac-api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"login": "admin", "password": "your-password", "lifetime": "1y"}'

License

MIT