Skip to main content
Glama
Spaceship MCP Server

Spaceship MCP Server

by mattcollins

Spaceship MCP Server

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

Related MCP server: Cloudflare DNS MCP Server

Status

I use this myself for my own projects.

  • Limited testing: As far as I know it is not in widespread use

  • Focused automated tests: Credential loading and MCP discovery are tested; live DNS operations are not

  • 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 the first page of DNS records for a domain (up to 100 records)

  • 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 ≥ 22

  • 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:

npm start

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.

Both environment variables also accept op://vault/item/field references. The server resolves these through the 1Password CLI (op must be on PATH) only when a tool makes its first API request. Starting the server and listing its tools do not access 1Password. Resolved credentials stay in memory for the server session; restart the server after rotating them. Failed credential reads can be retried by calling the tool again.

For this behavior, launch Node directly and pass the references as literal environment values. A launcher such as direnv with op read in .envrc or op run resolves credentials before server startup. Allow enough tool execution time for 1Password approval (for example, tool_timeout_sec = 120 in Codex).

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 DNS records for a domain (currently returns up to 100 records).

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.)

    • Additional fields are required depending on record type so the API can match the exact record:

      • A/AAAA: address

      • CNAME: cname

      • MX: exchange and preference

      • SRV: priority, weight, port, and target

      • TXT/other value-based records: value

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

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",
        "address": "192.0.2.1"
      }
    ]
  }
}

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 22 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 test - Build and test credential loading and MCP discovery without live API calls

  • npm start - Run the built server

Available Tools

10 tools
create_aaaa_recordA

Create an AAAA record (IPv6 address) for a domain

Inputs: name (required), domain (required), address (required), ttl.

create_a_recordA

Create an A record (IPv4 address) for a domain

Inputs: name (required), domain (required), address (required), ttl.

create_cname_recordB

Create a CNAME record (canonical name/alias) for a domain

Inputs: name (required), cname (required), domain (required), ttl.

create_dns_recordC

Create a new DNS record for a domain

Inputs: domain (required), records (required).

create_mx_recordB

Create an MX record (mail exchange) for a domain

Inputs: name (required), domain (required), exchange (required), priority (required), +1 more.

create_srv_recordA

Create an SRV record (service locator) for a domain

Inputs: name (required), port (required), domain (required), target (required), +3 more.

create_txt_recordB

Create a TXT record (text data) for a domain

Inputs: name (required), value (required), domain (required), ttl.

delete_dns_recordsA

Delete DNS records for a domain. Requires full record data matching the existing record.

Inputs: domain (required), records (required).

list_dns_recordsA

List all DNS records for a domain

Inputs: domain (required).

update_dns_recordsC

Update DNS records for a domain

Inputs: domain (required), records (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 10 tools

    Disambiguation2/5

    create_dns_record is ambiguous with the specific create_*_record tools; agents may not know which to use for a given record type. update_dns_records and delete_dns_records are clearly distinct, but the overlap between generic and specific creation tools creates confusion.

    Naming Consistency2/5

    Naming is inconsistent: some tools use singular 'dns_record' (create_dns_record) while others use plural 'dns_records' (list, update, delete). Also, generic and specific creation tools mix verb styles (create_dns_record vs create_a_record) without a clear pattern.

    Tool Count4/5

    10 tools is within a reasonable range for a DNS management server. However, the generic create_dns_record duplicates the specific create_*_record tools, making the count feel slightly padded. Still, the overall scope is well-covered.

    Completeness4/5

    The toolset covers the core DNS lifecycle: list, create, update, delete, plus specific types for common records (A, AAAA, CNAME, MX, SRV, TXT). Minor gaps exist, such as no get-single-record and missing less common record types, but these are workable.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers