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. - 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, TL
Add this skill
npx mdskills install bartwaardenburg/spaceship-mcpComprehensive MCP server with 48 tools, excellent documentation, and type-safe DNS record management
1# spaceship-mcp23[](https://www.npmjs.com/package/spaceship-mcp)4[](https://opensource.org/licenses/MIT)5[](https://nodejs.org/)6[](https://github.com/bartwaardenburg/spaceship-mcp/actions/workflows/ci.yml)7[](https://bartwaardenburg.github.io/spaceship-mcp/)8[](https://modelcontextprotocol.io)910A community-built [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for the [Spaceship](https://spaceship.com) API. Manage domains, DNS records, contacts, marketplace listings, and more — all through natural language via any MCP-compatible AI client.1112> **Note:** This is an unofficial, community-maintained project and is not affiliated with or endorsed by Spaceship.1314## Features1516- **48 tools** across 8 categories covering the full Spaceship API17- **13 DNS record types** with dedicated, type-safe creation tools (A, AAAA, ALIAS, CAA, CNAME, HTTPS, MX, NS, PTR, SRV, SVCB, TLSA, TXT)18- **Complete domain lifecycle** — register, renew, transfer, and restore domains19- **SellerHub integration** — list domains for sale and generate checkout links20- **DNS alignment analysis** — compare expected vs actual records to catch misconfigurations21- **WHOIS privacy and contact management** with TLD-specific attribute support22- **Input and output validation** via Zod schemas on every tool for safe, predictable operations23- **5 MCP Resources** for passive context loading (domain list, domain details, DNS records, contacts, SellerHub)24- **9 MCP Prompts** — 5 guided workflows and 4 with argument auto-complete25- **Resource subscriptions** with polling-based change detection and automatic notifications26- **Response caching** with configurable TTL and automatic invalidation on writes27- **Rate limit handling** with exponential backoff and `Retry-After` header support28- **Toolset filtering** to expose only the tool categories you need29- **Dynamic tool loading** mode for agents with constrained context windows30- **Actionable error messages** with context-aware recovery suggestions31- **Docker support** for containerized deployment32- **453 unit tests** with near-complete coverage3334## Supported Clients3536This MCP server works with any client that supports the Model Context Protocol, including:3738| Client | Easiest install |39|---|---|40| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | One-liner: `claude mcp add` |41| [Codex CLI](https://github.com/openai/codex) (OpenAI) | One-liner: `codex mcp add` |42| [Gemini CLI](https://github.com/google-gemini/gemini-cli) (Google) | One-liner: `gemini mcp add` |43| [VS Code](https://code.visualstudio.com/) (Copilot) | Command Palette: `MCP: Add Server` |44| [Claude Desktop](https://claude.ai/download) | JSON config file |45| [Cursor](https://cursor.com) | JSON config file |46| [Windsurf](https://codeium.com/windsurf) | JSON config file |47| [Cline](https://github.com/cline/cline) | UI settings |48| [Zed](https://zed.dev) | JSON settings file |4950## Installation5152### Claude Code5354```bash55claude mcp add --scope user spaceship-mcp \56 --env SPACESHIP_API_KEY=your-key \57 --env SPACESHIP_API_SECRET=your-secret \58 -- npx -y spaceship-mcp59```6061### Codex CLI (OpenAI)6263```bash64codex mcp add spaceship-mcp \65 --env SPACESHIP_API_KEY=your-key \66 --env SPACESHIP_API_SECRET=your-secret \67 -- npx -y spaceship-mcp68```6970### Gemini CLI (Google)7172```bash73gemini mcp add spaceship-mcp -- npx -y spaceship-mcp74```7576Set environment variables `SPACESHIP_API_KEY` and `SPACESHIP_API_SECRET` separately via `~/.gemini/settings.json`.7778### VS Code (Copilot)7980Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) > `MCP: Add Server` > select **Command (stdio)**.8182Or add to `.vscode/mcp.json` in your project directory:8384```json85{86 "servers": {87 "spaceship-mcp": {88 "type": "stdio",89 "command": "npx",90 "args": ["-y", "spaceship-mcp"],91 "env": {92 "SPACESHIP_API_KEY": "your-key",93 "SPACESHIP_API_SECRET": "your-secret"94 }95 }96 }97}98```99100### Claude Desktop / Cursor / Windsurf / Cline101102These clients share the same JSON format. Add the config below to the appropriate file:103104| Client | Config file |105|---|---|106| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |107| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |108| Cursor (project) | `.cursor/mcp.json` |109| Cursor (global) | `~/.cursor/mcp.json` |110| Windsurf | `~/.codeium/windsurf/mcp_config.json` |111| Cline | Settings > MCP Servers > Edit |112113```json114{115 "mcpServers": {116 "spaceship-mcp": {117 "command": "npx",118 "args": ["-y", "spaceship-mcp"],119 "env": {120 "SPACESHIP_API_KEY": "your-key",121 "SPACESHIP_API_SECRET": "your-secret"122 }123 }124 }125}126```127128### Zed129130Add to your Zed settings (`~/.zed/settings.json` on macOS, `~/.config/zed/settings.json` on Linux):131132```json133{134 "context_servers": {135 "spaceship-mcp": {136 "command": "npx",137 "args": ["-y", "spaceship-mcp"],138 "env": {139 "SPACESHIP_API_KEY": "your-key",140 "SPACESHIP_API_SECRET": "your-secret"141 }142 }143 }144}145```146147### Docker148149```bash150docker run -i --rm \151 -e SPACESHIP_API_KEY=your-key \152 -e SPACESHIP_API_SECRET=your-secret \153 ghcr.io/bartwaardenburg/spaceship-mcp154```155156### Codex CLI (TOML config alternative)157158If you prefer editing `~/.codex/config.toml` directly:159160```toml161[mcp_servers.spaceship-mcp]162command = "npx"163args = ["-y", "spaceship-mcp"]164env = { "SPACESHIP_API_KEY" = "your-key", "SPACESHIP_API_SECRET" = "your-secret" }165```166167### Other MCP Clients168169For any MCP-compatible client, use this server configuration:170171- **Command:** `npx`172- **Args:** `["-y", "spaceship-mcp"]`173- **Environment variables:** `SPACESHIP_API_KEY` and `SPACESHIP_API_SECRET`174175## Configuration176177### Required178179| Variable | Description |180|---|---|181| `SPACESHIP_API_KEY` | Your Spaceship API key |182| `SPACESHIP_API_SECRET` | Your Spaceship API secret |183184Generate your credentials in the [Spaceship API Manager](https://www.spaceship.com/application/api-manager/).185186### Optional187188| Variable | Description | Default |189|---|---|---|190| `SPACESHIP_CACHE_TTL` | Response cache lifetime in seconds. Set to `0` to disable caching. | `120` |191| `SPACESHIP_MAX_RETRIES` | Maximum retry attempts for rate-limited (429) requests with exponential backoff. | `3` |192| `SPACESHIP_TOOLSETS` | Comma-separated list of tool categories to enable (see [Toolset Filtering](#toolset-filtering)). | All toolsets |193| `SPACESHIP_DYNAMIC_TOOLS` | Set to `true` to enable dynamic tool loading mode (see [Dynamic Tool Loading](#dynamic-tool-loading)). | `false` |194195## API Key Setup196197### Creating Your API Key1981991. Log in to your [Spaceship account](https://www.spaceship.com)2002. Navigate to **API Manager** ([direct link](https://www.spaceship.com/application/api-manager/))2013. Click **New API key**2024. Give the key a descriptive name (e.g. "MCP Server")2035. Select the scopes you need (see below)2046. Copy both the **API key** and **API secret** — the secret is only shown once205206### Available Scopes207208Each scope controls access to a specific part of the Spaceship API. When creating your key, enable only the scopes you need.209210| Scope | Access |211|---|---|212| `domains:read` | List domains, check availability, view domain details and settings |213| `domains:write` | Modify domain settings (nameservers, auto-renew, contacts, privacy) |214| `domains:billing` | Register, renew, restore, and transfer domains (financial operations) |215| `domains:transfer` | Transfer lock, auth codes, and transfer status |216| `contacts:read` | Read saved contact profiles and attributes |217| `contacts:write` | Create and update contact profiles and attributes |218| `dnsrecords:read` | List DNS records for your domains |219| `dnsrecords:write` | Create, update, and delete DNS records |220| `sellerhub:read` | View marketplace listings and verification records |221| `sellerhub:write` | List/delist domains for sale, update pricing, generate checkout links |222| `asyncoperations:read` | Poll status of async operations (registration, renewal, transfer) |223224### Scopes Per Feature225226The table below shows which scopes are required for each group of tools.227228| Feature | Tools | Required scopes |229|---|---|---|230| **DNS Records** | `list_dns_records` | `dnsrecords:read` |231| | `save_dns_records`, `delete_dns_records`, all `create_*_record` tools | `dnsrecords:read` `dnsrecords:write` |232| **Domain Info** | `list_domains`, `get_domain`, `check_domain_availability` | `domains:read` |233| **Domain Settings** | `update_nameservers`, `set_auto_renew`, `set_privacy_level`, `set_email_protection`, `update_domain_contacts` | `domains:write` |234| **Domain Lifecycle** | `register_domain`, `renew_domain`, `restore_domain`, `transfer_domain` | `domains:billing` |235| **Transfer** | `set_transfer_lock`, `get_auth_code`, `get_transfer_status` | `domains:transfer` |236| **Contacts** | `get_contact`, `get_contact_attributes` | `contacts:read` |237| | `save_contact`, `save_contact_attributes` | `contacts:write` |238| **Personal NS** | `list_personal_nameservers`, `get_personal_nameserver` | `domains:read` |239| | `update_personal_nameserver`, `delete_personal_nameserver` | `domains:write` |240| **SellerHub** | `list_sellerhub_domains`, `get_sellerhub_domain`, `get_verification_records` | `sellerhub:read` |241| | `create_sellerhub_domain`, `update_sellerhub_domain`, `delete_sellerhub_domain`, `create_checkout_link` | `sellerhub:write` |242| **Async Operations** | `get_async_operation` | `asyncoperations:read` |243| **Analysis** | `check_dns_alignment` | `dnsrecords:read` |244245### Recommended Scope Presets246247**Full access** — enable everything for unrestricted use:248249```250domains:read domains:write domains:billing domains:transfer251contacts:read contacts:write252dnsrecords:read dnsrecords:write253sellerhub:read sellerhub:write254asyncoperations:read255```256257**DNS management only** — just read/write DNS records:258259```260dnsrecords:read dnsrecords:write261```262263**Read-only** — browse domains and records without making changes:264265```266domains:read contacts:read dnsrecords:read sellerhub:read asyncoperations:read267```268269## Available Tools270271### DNS Records272273| Tool | Description |274|---|---|275| `list_dns_records` | List all DNS records for a domain with pagination |276| `save_dns_records` | Save (upsert) DNS records — replaces records with the same name and type |277| `delete_dns_records` | Delete DNS records by name and type |278279### Type-Specific Record Creation280281Each DNS record type has a dedicated tool with type-safe parameters and validation.282283| Tool | Description |284|---|---|285| `create_a_record` | Create an A record (IPv4 address) |286| `create_aaaa_record` | Create an AAAA record (IPv6 address) |287| `create_alias_record` | Create an ALIAS record (CNAME flattening at zone apex) |288| `create_caa_record` | Create a CAA record (Certificate Authority Authorization) |289| `create_cname_record` | Create a CNAME record (canonical name) |290| `create_https_record` | Create an HTTPS record (SVCB-compatible) |291| `create_mx_record` | Create an MX record (mail exchange) |292| `create_ns_record` | Create an NS record (nameserver delegation) |293| `create_ptr_record` | Create a PTR record (reverse DNS) |294| `create_srv_record` | Create an SRV record (service locator) |295| `create_svcb_record` | Create an SVCB record (general service binding) |296| `create_tlsa_record` | Create a TLSA record (DANE/TLS certificate association) |297| `create_txt_record` | Create a TXT record (text data) |298299### Domain Management300301| Tool | Description |302|---|---|303| `list_domains` | List all domains in the account with pagination |304| `get_domain` | Get detailed domain information |305| `check_domain_availability` | Check availability for up to 20 domains at once |306| `update_nameservers` | Update nameservers for a domain |307| `set_auto_renew` | Toggle auto-renewal for a domain |308| `set_transfer_lock` | Toggle transfer lock for a domain |309| `get_auth_code` | Get the transfer auth/EPP code |310311### Domain Lifecycle312313| Tool | Description |314|---|---|315| `register_domain` | Register a new domain (financial operation, async) |316| `renew_domain` | Renew a domain registration (financial operation, async) |317| `restore_domain` | Restore a domain from redemption grace period (financial operation, async) |318| `transfer_domain` | Transfer a domain to Spaceship (financial operation, async) |319| `get_transfer_status` | Check the status of a domain transfer |320| `get_async_operation` | Poll the status of an async operation by its operation ID |321322### Contacts & Privacy323324| Tool | Description |325|---|---|326| `save_contact` | Create or update a reusable contact profile |327| `get_contact` | Retrieve a saved contact by ID |328| `save_contact_attributes` | Save TLD-specific contact attributes (e.g. tax IDs) |329| `get_contact_attributes` | Retrieve all stored contact attributes |330| `update_domain_contacts` | Update domain contacts (registrant, admin, tech, billing) |331| `set_privacy_level` | Set WHOIS privacy level (high or public) |332| `set_email_protection` | Toggle contact form display in WHOIS |333334### Personal Nameservers335336| Tool | Description |337|---|---|338| `list_personal_nameservers` | List vanity/glue nameservers for a domain |339| `get_personal_nameserver` | Get details of a personal nameserver by hostname |340| `update_personal_nameserver` | Create or update a personal nameserver (glue record) |341| `delete_personal_nameserver` | Delete a personal nameserver |342343### SellerHub344345| Tool | Description |346|---|---|347| `list_sellerhub_domains` | List domains for sale on the marketplace |348| `create_sellerhub_domain` | List a domain for sale with pricing |349| `get_sellerhub_domain` | Get listing details |350| `update_sellerhub_domain` | Update listing display name, description, and pricing |351| `delete_sellerhub_domain` | Remove a listing from the marketplace |352| `create_checkout_link` | Generate a buy-now checkout link for a listing |353| `get_verification_records` | Get DNS verification records for a listing |354355### Analysis356357| Tool | Description |358|---|---|359| `check_dns_alignment` | Compare expected vs actual DNS records to detect missing or unexpected entries |360361## MCP Resources362363Resources provide passive context that clients can load without calling tools.364365| Resource | URI | Description |366|---|---|---|367| Domain List | `spaceship://domains` | All domains in the account |368| Domain Details | `spaceship://domains/{domain}` | Detailed info for a specific domain |369| DNS Records | `spaceship://domains/{domain}/dns` | DNS records for a specific domain |370| Domain Contacts | `spaceship://domains/{domain}/contacts` | Contact assignments for a domain |371| SellerHub Listings | `spaceship://sellerhub` | All SellerHub marketplace listings |372373Clients that support resource subscriptions will receive automatic notifications when data changes (polled every 30 seconds).374375## MCP Prompts376377Prompts provide guided workflows that clients can present as slash commands or quick actions.378379### Guided Workflows380381| Prompt | Description |382|---|---|383| `setup-domain` | Register and configure a new domain (availability check, registration, DNS, privacy) |384| `audit-domain` | Health check for an existing domain (status, DNS, privacy, auto-renew, contacts) |385| `setup-email` | Configure email DNS records for Google Workspace, Microsoft 365, Fastmail, or a custom provider |386| `migrate-dns` | Step-by-step guide to migrate DNS records to Spaceship |387| `list-for-sale` | List a domain on the SellerHub marketplace with pricing and checkout link |388389### Auto-Complete Prompts390391These prompts support argument auto-complete for domain names and common values:392393| Prompt | Description |394|---|---|395| `domain-lookup` | Look up domain details with domain name auto-complete |396| `dns-records` | List DNS records with domain and record type auto-complete |397| `set-privacy` | Set WHOIS privacy with domain and level auto-complete |398| `update-nameservers` | Update nameservers with domain and provider auto-complete |399400## Toolset Filtering401402Reduce context window usage by enabling only the tool categories you need. Set the `SPACESHIP_TOOLSETS` environment variable to a comma-separated list:403404```bash405SPACESHIP_TOOLSETS=dns,domains406```407408| Toolset | Tools included |409|---|---|410| `domains` | Domain management and lifecycle tools |411| `dns` | DNS records, record creators, and analysis |412| `contacts` | Contact and privacy management |413| `privacy` | Privacy management (same tools as `contacts`) |414| `nameservers` | Personal nameserver management |415| `sellerhub` | SellerHub marketplace tools |416| `availability` | Domain availability checking |417418When not set, all toolsets are enabled. Invalid names are ignored; if all names are invalid, all toolsets are enabled as a fallback.419420## Dynamic Tool Loading421422For agents with constrained context windows, dynamic mode replaces all 48 tools with 3 lightweight meta-tools:423424```bash425SPACESHIP_DYNAMIC_TOOLS=true426```427428| Meta-Tool | Description |429|---|---|430| `search_tools` | Search available tools by keyword to discover what's available |431| `describe_tools` | Get full parameter schemas for one or more tools before executing |432| `execute_tool` | Execute any Spaceship tool by name with arguments |433434**Workflow:**4354361. `search_tools({ query: "dns" })` — discover relevant tools4372. `describe_tools({ tools: ["create_a_record"] })` — get the full parameter schema4383. `execute_tool({ tool: "create_a_record", arguments: { ... } })` — execute439440Resources, prompts, and completions remain available in dynamic mode.441442## Example Usage443444Once connected, you can interact with the Spaceship API using natural language:445446- "List all my domains"447- "Check if example.com is available for registration"448- "Create an A record for api.example.com pointing to 203.0.113.10"449- "Set up MX records for example.com to use Google Workspace"450- "Enable WHOIS privacy on example.com"451- "Check if my DNS records for example.com match what I expect"452- "List my domains for sale on SellerHub"453- "Transfer example.com to Spaceship"454455## Development456457```bash458# Install dependencies459pnpm install460461# Run in development mode462pnpm dev463464# Build for production465pnpm build466467# Run tests468pnpm test469470# Type check471pnpm typecheck472```473474### Project Structure475476```477src/478 index.ts # Entry point (stdio transport)479 server.ts # MCP server setup, toolset filtering, feature registration480 spaceship-client.ts # Spaceship API HTTP client with caching and retry481 cache.ts # TTL-based in-memory response cache482 schemas.ts # Shared Zod validation schemas483 output-schemas.ts # Zod output schemas for all 48 tools484 types.ts # TypeScript interfaces485 tool-result.ts # Error formatting with recovery suggestions486 resources.ts # MCP Resources (5 resources)487 resource-subscriptions.ts # Polling-based resource change notifications488 prompts.ts # MCP Prompts (5 guided workflows)489 completions.ts # MCP Prompts with argument auto-complete (4 prompts)490 dynamic-tools.ts # Dynamic tool loading meta-tools491 dns-utils.ts # DNS record formatting utilities492 update-checker.ts # NPM update notifications493 tools/494 dns-records.ts # List, save, delete DNS records495 dns-record-creators.ts # 13 type-specific DNS record creation tools496 domain-management.ts # Domain listing, settings, nameservers497 domain-lifecycle.ts # Registration, renewal, transfer, restore498 contacts-privacy.ts # Contact profiles and WHOIS privacy499 personal-nameservers.ts # Vanity/glue nameserver management500 sellerhub.ts # Marketplace listing and checkout tools501 analysis.ts # DNS alignment analysis502```503504## Requirements505506- Node.js >= 20507- A [Spaceship](https://spaceship.com) account with API credentials508509## License510511MIT - see [LICENSE](LICENSE) for details.512
Full transparency — inspect the skill content before installing.