serverscom-mcp

README

serverscom-mcp

MCP (Model Context Protocol) server for managing Servers.com dedicated server infrastructure. Enables AI assistants (Claude, etc.) to interact with the Servers.com API directly — query servers, manage SSH keys, configure networks, reinstall operating systems, and more.

Quick Start

npx @servers.com/mcp --token your-api-token

# or via env var
SC_TOKEN=your-api-token npx @servers.com/mcp

Usage with Claude Desktop

{
  "mcpServers": {
    "serverscom": {
      "command": "npx",
      "args": ["-y", "@servers.com/mcp"],
      "env": {
        "SC_TOKEN": "your-api-token"
      }
    }
  }
}

Configuration

Flag	Env var	Required	Default	Description
--token, -t	SC_TOKEN	yes	—	Servers.com API token
--endpoint, -e	SC_ENDPOINT	no	https://api.servers.com/v1	Custom API endpoint

Available Tools

Hosts

Tool	Description
list_hosts	List all hosts (dedicated servers, K8s baremetal nodes, SBM) with optional filtering by search pattern, location, type, and labels

Dedicated Servers

Tool	Description
get_dedicated_server	Get detailed server info: configuration, status, operational_status, power_status
update_dedicated_server	Update title, labels, user_data (cloud-init), or ipxe_config
list_dedicated_server_features	List features and their status for a server

Features

Each feature supports activate_* and deactivate_* operations. All feature changes are asynchronous — poll list_dedicated_server_features until the desired status is reached.

Feature	Description
disaggregated_public_ports	Disaggregated public ports
disaggregated_private_ports	Disaggregated private ports
no_public_ip_address	No default public IP; restricts rescue mode, OOB access, additional public networks
no_private_ip	No default private IP
no_public_network	Public interface is not configured at all (more restrictive than no_public_ip_address)
host_rescue_mode	Rescue mode (requires auth_methods and optionally ssh_key_fingerprints)
oob_public_access	Out-of-band public access
private_ipxe_boot	Private iPXE boot (requires ipxe_config)

SSH Keys

Tool	Description
list_ssh_keys	List all SSH keys in the account
get_ssh_key	Get key details by fingerprint
create_ssh_key	Create a new SSH key
update_ssh_key	Update key name or labels
delete_ssh_key	Delete an SSH key
list_dedicated_server_ssh_keys	List keys attached to a server
attach_ssh_keys_to_dedicated_server	Attach SSH keys to a server
detach_ssh_key_from_dedicated_server	Detach an SSH key from a server

Power Management

All power operations are asynchronous — poll get_dedicated_server and check power_status.

Tool	Description
power_on_dedicated_server	Power on
power_off_dedicated_server	Power off
power_cycle_dedicated_server	Hard reboot

OS Reinstallation

Tool	Description
reinstall_dedicated_server	Reinstall OS with custom partition layout, RAID config, and SSH key injection. Async — operational_status transitions to installation, then back to normal

Supports custom partition layouts and RAID configuration. Max 1 SSH key per reinstall.

Networks

Tool	Description
list_dedicated_server_networks	List all networks (public/private, IPv4/IPv6) attached to a server
get_dedicated_server_network	Get network details: CIDR, family, interface type, distribution method, status
get_dedicated_server_network_usage	Check current and committed bandwidth utilization
add_dedicated_server_public_ipv4_network	Add additional public IPv4 network (gateway or route)
add_dedicated_server_private_ipv4_network	Add additional private IPv4 network (gateway or route)
activate_dedicated_server_public_ipv6_network	Activate IPv6 (one allocation per server)
delete_dedicated_server_network	Remove an additional network (default network cannot be deleted)

Network Quotas

• Route (alias) networks: max 32 IPs per server
• Additional gateway networks per family (public/private IPv4): max 2 additional
• Total IPs across all gateway networks per family: max 72 (e.g. if default is /29 = 8 IPs, only 64 remain)
• IPv6: max 1 allocation per server (either a single /64 or a /125 + /64 depending on location)

Locations & Infrastructure Options

Tool	Description
list_locations / get_location	Data center locations
list_server_model_options / get_server_model_option	Available server models per location
list_ram_options	RAM upgrade options
list_os_options / get_os_option	Available operating systems
list_drive_model_options / get_drive_model_option	Available drive models
list_uplink_options / get_uplink_option	Network uplink options
list_bandwidth_options / get_bandwidth_option	Bandwidth plans
list_sbm_flavor_options / get_sbm_flavor_option	Scalable Bare Metal (SBM) flavors
list_sbm_os_options	OS options for SBM servers

Storage

Tool	Description
list_dedicated_server_drive_slots	List all drive slots and installed drives for a server

Async Operations

Many operations are asynchronous. After calling them, poll the relevant status field:

Operation	Poll with	Field to watch
Feature changes	list_dedicated_server_features	feature status
Rescue mode	get_dedicated_server	operational_status
OS reinstallation	get_dedicated_server	operational_status
Power changes	get_dedicated_server	power_status

operational_status values: normal → provisioning → installation → entering_rescue_mode → rescue_mode → exiting_rescue_mode → maintenance

License

MIT

---

Development

Building from source

go build -o serverscom-mcp .

Releasing

Releases are automated via GoReleaser and GitHub Actions. Push a version tag to trigger the pipeline:

git tag v1.2.3
git push origin v1.2.3

The workflow will:

1. Build binaries for Linux, macOS, Windows (amd64 + arm64)
2. Create a GitHub Release with archives and checksums
3. Publish @servers.com/mcp and platform packages to npm using trusted publishing (OIDC, no long-lived tokens)

Project Structure

serverscom-mcp/
├── main.go                       # Entry point
└── internal/tools/
    ├── tools.go                  # Tool registration hub, shared helpers
    ├── hosts.go                  # list_hosts
    ├── dedicated_servers.go      # Server CRUD and feature management
    ├── ssh_keys.go               # SSH key operations
    ├── locations.go              # Location and infrastructure options
    ├── power.go                  # Power management
    ├── drives.go                 # Drive slot listing
    ├── reinstall.go              # OS reinstallation
    └── networks.go               # Network management