spaceship-mcp

A community-built Model Context Protocol (MCP) server for the Spaceship API. Manage domains, DNS records, contacts, marketplace listings, and more — all through natural language via any MCP-compatible AI client.

Note: This is an unofficial, community-maintained project and is not affiliated with or endorsed by Spaceship.

Add To Your Editor

CLI one-liners — the fastest way to get started. Pick your tool:

Claude Code

claude mcp add --scope user spaceship-mcp \
  --env SPACESHIP_API_KEY=your-key \
  --env SPACESHIP_API_SECRET=your-secret \
  -- npx -y spaceship-mcp

Codex CLI (OpenAI)

codex mcp add spaceship-mcp \
  --env SPACESHIP_API_KEY=your-key \
  --env SPACESHIP_API_SECRET=your-secret \
  -- npx -y spaceship-mcp

Gemini CLI (Google)

gemini mcp add spaceship-mcp -- npx -y spaceship-mcp

Set environment variables SPACESHIP_API_KEY and SPACESHIP_API_SECRET separately via ~/.gemini/settings.json.

VS Code (Copilot)

Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) > MCP: Add Server > select Command (stdio).

Or add to .vscode/mcp.json in your project directory:

{
  "servers": {
    "spaceship-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "spaceship-mcp"],
      "env": {
        "SPACESHIP_API_KEY": "your-key",
        "SPACESHIP_API_SECRET": "your-secret"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "spaceship-mcp": {
      "command": "npx",
      "args": ["-y", "spaceship-mcp"],
      "env": {
        "SPACESHIP_API_KEY": "your-key",
        "SPACESHIP_API_SECRET": "your-secret"
      }
    }
  }
}

Supported Clients

This MCP server works with any client that supports the Model Context Protocol, including:

{
  "mcpServers": {
    "spaceship-mcp": {
      "command": "npx",
      "args": ["-y", "spaceship-mcp"],
      "env": {
        "SPACESHIP_API_KEY": "your-key",
        "SPACESHIP_API_SECRET": "your-secret"
      }
    }
  }
}

{
  "mcpServers": {
    "spaceship-mcp": {
      "command": "npx",
      "args": ["-y", "spaceship-mcp"],
      "env": {
        "SPACESHIP_API_KEY": "your-key",
        "SPACESHIP_API_SECRET": "your-secret"
      }
    }
  }
}

{
  "context_servers": {
    "spaceship-mcp": {
      "command": "npx",
      "args": ["-y", "spaceship-mcp"],
      "env": {
        "SPACESHIP_API_KEY": "your-key",
        "SPACESHIP_API_SECRET": "your-secret"
      }
    }
  }
}

docker run -i --rm \
  -e SPACESHIP_API_KEY=your-key \
  -e SPACESHIP_API_SECRET=your-secret \
  ghcr.io/bartwaardenburg/spaceship-mcp

[mcp_servers.spaceship-mcp]
command = "npx"
args = ["-y", "spaceship-mcp"]
env = { "SPACESHIP_API_KEY" = "your-key", "SPACESHIP_API_SECRET" = "your-secret" }

Features

• 48 tools across 8 categories covering the full Spaceship API
• 13 DNS record types with dedicated, type-safe creation tools (A, AAAA, ALIAS, CAA, CNAME, HTTPS, MX, NS, PTR, SRV, SVCB, TLSA, TXT)
• Complete domain lifecycle — register, renew, transfer, and restore domains
• SellerHub integration — list domains for sale and generate checkout links
• DNS alignment analysis — compare expected vs actual records to catch misconfigurations
• WHOIS privacy and contact management with TLD-specific attribute support
• Input and output validation via Zod schemas on every tool for safe, predictable operations
• 5 MCP Resources for passive context loading (domain list, domain details, DNS records, contacts, SellerHub)
• 9 MCP Prompts — 5 guided workflows and 4 with argument auto-complete
• Resource subscriptions with polling-based change detection and automatic notifications
• Response caching with configurable TTL and automatic invalidation on writes
• Rate limit handling with exponential backoff and Retry-After header support
• Toolset filtering to expose only the tool categories you need
• Dynamic tool loading mode for agents with constrained context windows
• Actionable error messages with context-aware recovery suggestions
• Docker support for containerized deployment
• 453 unit tests with near-complete coverage

Configuration

Required

Generate your credentials in the Spaceship API Manager.

Optional

API Key Setup

Creating Your API Key

1. Log in to your Spaceship account
2. Navigate to API Manager (direct link)
3. Click New API key
4. Give the key a descriptive name (e.g. "MCP Server")
5. Select the scopes you need (see below)
6. Copy both the API key and API secret — the secret is only shown once

Available Scopes

Each scope controls access to a specific part of the Spaceship API. When creating your key, enable only the scopes you need.

Scopes Per Feature

The table below shows which scopes are required for each group of tools.

Recommended Scope Presets

Full access — enable everything for unrestricted use:

domains:read  domains:write  domains:billing  domains:transfer
contacts:read  contacts:write
dnsrecords:read  dnsrecords:write
sellerhub:read  sellerhub:write
asyncoperations:read

DNS management only — just read/write DNS records:

dnsrecords:read  dnsrecords:write

Read-only — browse domains and records without making changes:

domains:read  contacts:read  dnsrecords:read  sellerhub:read  asyncoperations:read

Available Tools

DNS Records

Type-Specific Record Creation

Each DNS record type has a dedicated tool with type-safe parameters and validation.

Domain Management

Domain Lifecycle

Contacts & Privacy

Personal Nameservers

SellerHub

Analysis

MCP Resources

Resources provide passive context that clients can load without calling tools.

Clients that support resource subscriptions will receive automatic notifications when data changes (polled every 30 seconds).

MCP Prompts

Prompts provide guided workflows that clients can present as slash commands or quick actions.

Guided Workflows

Auto-Complete Prompts

These prompts support argument auto-complete for domain names and common values:

Toolset Filtering

Reduce context window usage by enabling only the tool categories you need. Set the SPACESHIP_TOOLSETS environment variable to a comma-separated list:

SPACESHIP_TOOLSETS=dns,domains

When not set, all toolsets are enabled. Invalid names are ignored; if all names are invalid, all toolsets are enabled as a fallback.

Dynamic Tool Loading

For agents with constrained context windows, dynamic mode replaces all 48 tools with 3 lightweight meta-tools:

SPACESHIP_DYNAMIC_TOOLS=true

Workflow:

1. search_tools({ query: "dns" }) — discover relevant tools
2. describe_tools({ tools: ["create_a_record"] }) — get the full parameter schema
3. execute_tool({ tool: "create_a_record", arguments: { ... } }) — execute

Resources, prompts, and completions remain available in dynamic mode.

Security Notes

• Trust model: Any prompt or agent allowed to call this MCP server can execute Spaceship API actions with the configured credentials.
• Least-privilege credentials: Use separate Spaceship API keys per environment/team/use case and enable only the scopes you need (see Available Scopes).
• Write-action approvals: Enable host-side approvals for mutating tools (register_domain, create_*, update_*, delete_*, save_*, set_*, and lifecycle operations).
• Team config governance: Keep shared MCP config in version control, require review for changes to command/args/env/toolset filtering, and keep secrets in a vault or host secret manager (not in plain-text repo files).

Example Usage

Once connected, you can interact with the Spaceship API using natural language:

• "List all my domains"
• "Check if example.com is available for registration"
• "Create an A record for api.example.com pointing to 203.0.113.10"
• "Set up MX records for example.com to use Google Workspace"
• "Enable WHOIS privacy on example.com"
• "Check if my DNS records for example.com match what I expect"
• "List my domains for sale on SellerHub"
• "Transfer example.com to Spaceship"

Community

• Support: SUPPORT.md
• Security reporting: SECURITY.md
• Contributing guidelines: CONTRIBUTING.md
• Bug reports and feature requests: Issues

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

Project Structure

src/
  index.ts                    # Entry point (stdio transport)
  server.ts                   # MCP server setup, toolset filtering, feature registration
  spaceship-client.ts         # Spaceship API HTTP client with caching and retry
  cache.ts                    # TTL-based in-memory response cache
  schemas.ts                  # Shared Zod validation schemas
  output-schemas.ts           # Zod output schemas for all 48 tools
  types.ts                    # TypeScript interfaces
  tool-result.ts              # Error formatting with recovery suggestions
  resources.ts                # MCP Resources (5 resources)
  resource-subscriptions.ts   # Polling-based resource change notifications
  prompts.ts                  # MCP Prompts (5 guided workflows)
  completions.ts              # MCP Prompts with argument auto-complete (4 prompts)
  dynamic-tools.ts            # Dynamic tool loading meta-tools
  dns-utils.ts                # DNS record formatting utilities
  update-checker.ts           # NPM update notifications
  tools/
    dns-records.ts            # List, save, delete DNS records
    dns-record-creators.ts    # 13 type-specific DNS record creation tools
    domain-management.ts      # Domain listing, settings, nameservers
    domain-lifecycle.ts       # Registration, renewal, transfer, restore
    contacts-privacy.ts       # Contact profiles and WHOIS privacy
    personal-nameservers.ts   # Vanity/glue nameserver management
    sellerhub.ts              # Marketplace listing and checkout tools
    analysis.ts               # DNS alignment analysis

Requirements

• Node.js >= 20
• A Spaceship account with API credentials

License

MIT - see LICENSE for details.