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:
Claude Desktop / Cowork
Cowork runs inside Claude Desktop and uses the same connected MCP servers and permissions. Configure once in Claude Desktop, then the server is available in Cowork.
Add the following to your Claude Desktop config file:
{
"mcpServers": {
"spaceship-mcp": {
"command": "npx",
"args": ["-y", "spaceship-mcp"],
"env": {
"SPACESHIP_API_KEY": "your-key",
"SPACESHIP_API_SECRET": "your-secret"
}
}
}
}
Windsurf / Cline / Zed
Windsurf — add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"spaceship-mcp": {
"command": "npx",
"args": ["-y", "spaceship-mcp"],
"env": {
"SPACESHIP_API_KEY": "your-key",
"SPACESHIP_API_SECRET": "your-secret"
}
}
}
}
Cline — open Settings > MCP Servers > Edit, then add the same mcpServers block shown above.
Zed — add to your Zed settings (~/.zed/settings.json on macOS, ~/.config/zed/settings.json on Linux):
{
"context_servers": {
"spaceship-mcp": {
"command": "npx",
"args": ["-y", "spaceship-mcp"],
"env": {
"SPACESHIP_API_KEY": "your-key",
"SPACESHIP_API_SECRET": "your-secret"
}
}
}
}
Docker
docker run -i --rm \
-e SPACESHIP_API_KEY=your-key \
-e SPACESHIP_API_SECRET=your-secret \
ghcr.io/bartwaardenburg/spaceship-mcp
Generic MCP Server Config
Use this as the baseline in any host:
- Command:
npx - Args:
["-y", "spaceship-mcp"] - Required env vars:
SPACESHIP_API_KEY,SPACESHIP_API_SECRET - Optional env vars:
SPACESHIP_CACHE_TTL,SPACESHIP_MAX_RETRIES,SPACESHIP_TOOLSETS,SPACESHIP_DYNAMIC_TOOLS(see Configuration)
Host key mapping:
Codex CLI (TOML config alternative)
If you prefer editing ~/.codex/config.toml directly:
[mcp_servers.spaceship-mcp]
command = "npx"
args = ["-y", "spaceship-mcp"]
env = { "SPACESHIP_API_KEY" = "your-key", "SPACESHIP_API_SECRET" = "your-secret" }
Other MCP Clients
For any MCP-compatible client, use this server configuration:
- Command:
npx - Args:
["-y", "spaceship-mcp"] - Environment variables:
SPACESHIP_API_KEYandSPACESHIP_API_SECRET
Claude Ecosystem Notes
Claude currently has multiple MCP-related concepts that are easy to mix up:
- Local MCP servers (Claude Desktop): defined in
claude_desktop_config.jsonand started on your machine (docs). - Cowork: reuses the MCP servers connected in Claude Desktop (docs).
- Connectors: remote MCP integrations managed in Claude (docs).
- Cowork plugins: Claude-specific workflow packaging (instructions + tools/data integrations) (docs). Useful in Claude, but not portable as a generic MCP server config for other agent clients.
Verified against vendor docs on 2026-03-05.
Terminology
What is portable across hosts:
- MCP server runtime settings (
command,args,env) - Transport model (
stdiocommand server) - Tool names and tool schemas exposed by this server
What is host/vendor-specific (not portable as-is):
- Host config key names (
servers,mcpServers,context_servers,mcp_servers) - Host UX/workflows for adding servers (CLI commands, UI menus, settings paths)
- Anthropic-specific concepts such as Claude Desktop local MCP servers, Claude Connectors via remote MCP, and Claude Code plugins used in Cowork workflows
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-Afterheader 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
- Log in to your Spaceship account
- Navigate to API Manager (direct link)
- Click New API key
- Give the key a descriptive name (e.g. "MCP Server")
- Select the scopes you need (see below)
- 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:
search_tools({ query: "dns" })— discover relevant toolsdescribe_tools({ tools: ["create_a_record"] })— get the full parameter schemaexecute_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.