foreman-mcp-server

zeddy89/foreman-mcp-server

3.2

If you are the rightful owner of foreman-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Foreman MCP Server is a Model Context Protocol server that provides natural language access to Foreman API endpoints, facilitating easier management of Foreman resources.

Tools
5
Resources
0
Prompts
0

Foreman MCP Server

An MCP (Model Context Protocol) server that provides natural language access to Foreman API endpoints.

Features

  • Complete coverage of major Foreman API endpoints
  • Natural language processing for common operations
  • Support for host, content view, repository, and organization management
  • Task monitoring and management
  • Secure authentication handling

Installation

cd foreman-mcp-server
npm install
npm run build

Configuration

The server can be configured using either environment variables or a configuration file.

Option 1: Environment Variables

export FOREMAN_URL="https://your-foreman-instance.com"
export FOREMAN_USERNAME="your-username"
export FOREMAN_TOKEN="your-personal-access-token"

Option 2: Configuration File (Single Server)

Create a foreman-config.json file in the project root:

{
  "baseUrl": "https://your-foreman-instance.com",
  "username": "your-username",
  "token": "your-personal-access-token"
}

Option 3: Configuration File (Multiple Servers)

To support multiple Foreman/Satellite servers, use this format:

{
  "servers": {
    "foreman": {
      "baseUrl": "https://your-foreman-server.com",
      "username": "foreman-admin",
      "token": "foreman-token"
    },
    "satellite": {
      "baseUrl": "https://your-satellite-server.com",
      "username": "satellite-admin",
      "token": "satellite-token"
    },
    "dev": {
      "baseUrl": "https://dev-foreman.example.com",
      "username": "dev-admin",
      "token": "dev-token"
    }
  },
  "defaultServer": "foreman"
}

Note: The configuration file is ignored by git for security. Never commit credentials.

Generating a Personal Access Token

To generate a Personal Access Token in Foreman:

  1. Log in to your Foreman instance
  2. Navigate to your user account settings
  3. Go to the "Personal Access Tokens" section
  4. Create a new token with appropriate permissions

Note: The token is used as the password in HTTP Basic authentication with your username.

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "foreman": {
      "command": "node",
      "args": ["/path/to/foreman-mcp-server/dist/index.js"],
      "env": {
        "FOREMAN_URL": "https://your-foreman-instance.com",
        "FOREMAN_USERNAME": "your-username",
        "FOREMAN_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Available Tools

All tools support an optional server parameter to specify which server to use. If not specified, the default server is used.

Host Management

  • foreman_list_hosts - List all hosts with optional filters
  • foreman_get_host - Get detailed information about a specific host
  • foreman_create_host - Create a new host
  • foreman_update_host - Update an existing host
  • foreman_delete_host - Delete a host
  • foreman_power_host - Perform power management actions (start, stop, reboot, etc.)

Content View Management

  • foreman_list_content_views - List all content views
  • foreman_get_content_view - Get detailed information about a content view
  • foreman_create_content_view - Create a new content view
  • foreman_publish_content_view - Publish a new version of a content view

Repository Management

  • foreman_list_repositories - List all repositories
  • foreman_create_repository - Create a new repository
  • foreman_sync_repository - Synchronize a repository

Organization Management

  • foreman_list_organizations - List all organizations
  • foreman_create_organization - Create a new organization

Task Management

  • foreman_list_tasks - List Foreman tasks with filters for state and result

Provisioning Tools

Installation Media
  • foreman_list_media - List all installation media
  • foreman_get_medium - Get details of an installation medium
  • foreman_create_medium - Create a new installation medium
  • foreman_update_medium - Update an installation medium
  • foreman_delete_medium - Delete an installation medium
Partition Tables
  • foreman_list_partition_tables - List all partition tables
  • foreman_get_partition_table - Get details of a partition table
  • foreman_create_partition_table - Create a new partition table
  • foreman_update_partition_table - Update a partition table
  • foreman_delete_partition_table - Delete a partition table
Operating Systems
  • foreman_list_operating_systems - List all operating systems
  • foreman_get_operating_system - Get details of an operating system
  • foreman_create_operating_system - Create a new operating system
  • foreman_update_operating_system - Update an operating system
  • foreman_delete_operating_system - Delete an operating system

Natural Language Examples

The server includes natural language processing capabilities. You can use phrases like:

  • "List all hosts"
  • "Show me hosts in organization ACME"
  • "Create a host named webserver01"
  • "Reboot host database01"
  • "Publish content view production-cv"
  • "Sync repository centos-base"
  • "List running tasks"
  • "Show failed tasks"

Using Multiple Servers

When you have multiple servers configured, you can specify which server to use:

Using Tool Parameters

// List hosts from the satellite server
foreman_list_hosts({ server: "satellite" })

// Create a host on the dev server
foreman_create_host({ 
  server: "dev",
  name: "test-host",
  organization_id: "1",
  location_id: "1"
})

// Query different servers
foreman_list_organizations({ server: "foreman" })
foreman_list_organizations({ server: "satellite" })

Natural Language with Server Specification

  • "List all hosts on the satellite server"
  • "Show me content views from the dev server"
  • "Create a repository on satellite"

Development

# Run in development mode
npm run dev

# Build for production
npm run build

# Start production server
npm start

Security Notes

  • Authentication uses Personal Access Tokens (PAT) for enhanced security
  • Tokens are passed via environment variables
  • All API calls use HTTPS
  • SSL certificate verification can be disabled for self-signed certificates
  • Never commit tokens or credentials to version control

Extending the Server

To add new API endpoints:

  1. Add methods to foreman-client.ts
  2. Define tool schemas and handlers in index.ts
  3. Add natural language patterns to natural-language.ts

Troubleshooting

  • Ensure Foreman API v2 is accessible at the configured URL
  • Verify credentials have appropriate permissions
  • Check that the Foreman instance allows API access from your IP
  • The server automatically handles self-signed SSL certificates
  • For additional SSL debugging, you may set NODE_TLS_REJECT_UNAUTHORIZED=0 (not recommended for production)