GitHub - mattcollins/spaceship-mcp: An MCP (Model Context Protocol) server for the Spaceship API, providing tools to manage DNS records.

An MCP (Model Context Protocol) server for the Spaceship API, providing easy-to-use tools for managing DNS records. Features specialized tools for common record types (A, AAAA, CNAME, MX, SRV, TXT) with explicit parameters, plus generic tools for advanced use cases.

⚠️ Warning: use with care

This MCP server gives AI agents direct control over your DNS records. This can be helpful but also dangerous because:

Domain takeover risk: Incorrect DNS changes could redirect your domain to malicious sites
Service disruption: Wrong DNS records can make your websites and services inaccessible
Permanent consequences: Some DNS changes can have lasting effects on your domain's reputation
Unintended modifications: AI agents may make DNS changes you didn't expect or want

Recommendations:

Review AI-suggested DNS changes before confirming them
Keep backups of your current DNS configuration
Monitor your domains closely when using this server
Avoid using it with an AI agent that may also be accessing untrusted content

Status

I use this myself for my own projects.

Limited testing: As far as I know it is not in widespread use
No automated tests: There are currently no unit tests or integration tests
Use at your own risk: Suitable for experimentation but not recommended for critical systems

Contributions, bug reports, and feedback are welcome to help improve the project's stability and reliability.

Features

Core Operations

List DNS Records: Retrieve all DNS records for a domain
Delete DNS Records: Remove DNS records from a domain

Specialized Record Creation Tools

Type-specific tools with explicit parameters for easy, error-free DNS management:

A Records: Create IPv4 address records
AAAA Records: Create IPv6 address records
CNAME Records: Create canonical name aliases
MX Records: Create mail exchange records with priority and exchange parameters
SRV Records: Create service locator records with priority, weight, port, and target
TXT Records: Create text records for SPF, DKIM, DMARC, verification, etc.

Generic Tools

Create/Update DNS Records: Generic tools supporting all DNS record types for advanced use cases

Installation

Prerequisites

Node.js ≥ 18
An MCP-compatible client (e.g. Claude Desktop, Cursor, Continue)
Spaceship API credentials (see Configuration section below)

Install the server

Clone the repository and build:

git clone https://github.com/mattcollins/spaceship-mcp.git
cd spaceship-mcp
npm install
npm run build

Configure your MCP client

Add the server to your MCP client configuration.

Example (Claude Desktop)

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "spaceship": {
      "command": "node",
      "args": ["/absolute/path/to/spaceship-mcp/dist/index.js"],
      "env": {
        "SPACESHIP_API_KEY": "your_api_key",
        "SPACESHIP_API_SECRET": "your_api_secret"
      }
    }
  }
}

Replace /absolute/path/to/spaceship-mcp with the actual path where you cloned the repository.

Restart the client after saving the file.

Verify the installation

After restarting your client, confirm the server is running:

The server appears in the client's MCP/server list
No errors appear in the client logs
Tools exposed by the server (like list_dns_records) are available to the model

To check for startup errors, you can run the server manually:

Configuration

Environment Variables

Variable	Description	Required
`SPACESHIP_API_KEY`	Your Spaceship API key	Yes
`SPACESHIP_API_SECRET`	Your Spaceship API secret	Yes

Get your API credentials from the Spaceship API Manager.

Required API Permissions

Your API key will need the following permissions:

dnsrecords:read - For listing DNS records
dnsrecords:write - For creating, updating, and deleting DNS records

Usage

Available Tools

`list_dns_records`

Lists all DNS records for a domain.

Parameters:

domain (string, required): The domain name to list DNS records for

`create_dns_record`

Creates new DNS records for a domain.

Parameters:

domain (string, required): The domain name
records (array, required): Array of DNS records to create
- name (string, required): The record name (subdomain)
- type (string, required): The record type (A, AAAA, CNAME, MX, TXT, etc.)
- value (string, required): The record value
- ttl (number, optional): Time to live in seconds (default: 3600)

`update_dns_records`

Updates DNS records for a domain.

Parameters:

domain (string, required): The domain name
records (array, required): Array of DNS records to update
- name (string, required): The record name (subdomain)
- type (string, required): The record type (A, AAAA, CNAME, MX, TXT, etc.)
- value (string, required): The record value
- ttl (number, optional): Time to live in seconds (default: 3600)

`delete_dns_records`

Deletes DNS records from a domain.

Parameters:

domain (string, required): The domain name
records (array, required): Array of DNS records to delete
- name (string, required): The record name (subdomain)
- type (string, required): The record type (A, AAAA, CNAME, MX, TXT, etc.)

Specialized Record Type Tools

For convenience, specialized tools are available for common DNS record types. These tools provide explicit parameters instead of requiring format strings.

`create_a_record`

Creates an A record (IPv4 address).

Parameters:

domain (string, required): The domain name
name (string, required): The record name (subdomain, use "@" for root)
address (string, required): The IPv4 address (e.g., "192.0.2.1")
ttl (number, optional): Time to live in seconds (default: 3600)

`create_aaaa_record`

Creates an AAAA record (IPv6 address).

Parameters:

domain (string, required): The domain name
name (string, required): The record name (subdomain, use "@" for root)
address (string, required): The IPv6 address (e.g., "2001:db8::1")
ttl (number, optional): Time to live in seconds (default: 3600)

`create_cname_record`

Creates a CNAME record (canonical name/alias).

Parameters:

domain (string, required): The domain name
name (string, required): The record name (subdomain)
cname (string, required): The canonical name to point to
ttl (number, optional): Time to live in seconds (default: 3600)

Note: CNAME values typically should not include a trailing dot for Spaceship DNS.

`create_mx_record`

Creates an MX record (mail exchange).

Parameters:

domain (string, required): The domain name
name (string, required): The record name (subdomain, use "@" for root)
priority (number, required): The priority value (lower is higher priority, e.g., 10)
exchange (string, required): The mail server hostname
ttl (number, optional): Time to live in seconds (default: 3600)

`create_srv_record`

Creates an SRV record (service locator).

Parameters:

domain (string, required): The domain name
name (string, required): The service name (e.g., "_autodiscover._tcp")
priority (number, required): The priority value (lower is higher priority)
weight (number, required): The weight for load balancing
port (number, required): The port number
target (string, required): The target hostname
ttl (number, optional): Time to live in seconds (default: 3600)

`create_txt_record`

Creates a TXT record (text data).

Parameters:

domain (string, required): The domain name
name (string, required): The record name (subdomain, use "@" for root)
value (string, required): The text value
ttl (number, optional): Time to live in seconds (default: 3600)

Example Usage

Using Specialized Tools (Recommended)

The specialized tools provide a cleaner interface with explicit parameters:

Create an A Record

{
  "tool": "create_a_record",
  "arguments": {
    "domain": "example.com",
    "name": "www",
    "address": "192.0.2.1"
  }
}

Create an MX Record

{
  "tool": "create_mx_record",
  "arguments": {
    "domain": "example.com",
    "name": "@",
    "priority": 10,
    "exchange": "mail.example.com"
  }
}

Create an SRV Record

{
  "tool": "create_srv_record",
  "arguments": {
    "domain": "example.com",
    "name": "_autodiscover._tcp",
    "priority": 0,
    "weight": 1,
    "port": 443,
    "target": "autodiscover.example.com"
  }
}

Create a TXT Record

{
  "tool": "create_txt_record",
  "arguments": {
    "domain": "example.com",
    "name": "@",
    "value": "v=spf1 include:spf.example.com -all"
  }
}

Create a CNAME Record

{
  "tool": "create_cname_record",
  "arguments": {
    "domain": "example.com",
    "name": "www",
    "cname": "example.com"
  }
}

Using Generic Tools

The generic tools are still available and support all record types:

List DNS Records

{
  "tool": "list_dns_records",
  "arguments": {
    "domain": "example.com"
  }
}

Create DNS Record (Generic)

{
  "tool": "create_dns_record",
  "arguments": {
    "domain": "example.com",
    "records": [
      {
        "name": "www",
        "type": "A",
        "value": "192.0.2.1",
        "ttl": 3600
      }
    ]
  }
}

Note: For MX records, use format "priority exchange" (e.g., "10 mail.example.com"). For SRV records, use format "priority weight port target" (e.g., "0 1 443 autodiscover.example.com").

Delete DNS Records

{
  "tool": "delete_dns_records",
  "arguments": {
    "domain": "example.com",
    "records": [
      {
        "name": "www",
        "type": "A"
      }
    ]
  }
}

Error Handling

The server will return appropriate error messages for:

Invalid API credentials
Missing required parameters
API rate limits
Network errors
Invalid domain names

Troubleshooting

Server not appearing in client

Ensure the command path is correct and points to the built dist/index.js file
Use an absolute path in the configuration, not a relative path
Check that the project has been built with npm run build

Authentication errors

Verify your API credentials are correct in the configuration
Check that your API key has the required permissions (dnsrecords:read and dnsrecords:write)
Ensure environment variables are properly set in your client configuration

Node version issues

Check your Node version with node --version
Ensure you're running Node.js 18 or higher
If you have multiple Node versions, ensure your MCP client is using the correct one

Debugging startup errors

Run the server manually to see detailed error messages:

cd /path/to/spaceship-mcp
npm start

Check your MCP client logs for additional error information.

Development

npm run dev - Watch mode for development
npm run build - Build the TypeScript code
npm start - Run the built server