Spaceship MCP

spaceship-mcp

Un servidor Model Context Protocol (MCP) construido por la comunidad para la API de Spaceship. Gestiona dominios, registros DNS, contactos, listados de marketplace y más, todo mediante lenguaje natural a través de cualquier cliente de IA compatible con MCP.

Nota: Este es un proyecto no oficial mantenido por la comunidad y no está afiliado ni respaldado por Spaceship.

Añadir a tu editor

Comandos de una línea: la forma más rápida de empezar. Elige tu herramienta:

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

Configura las variables de entorno SPACESHIP_API_KEY y SPACESHIP_API_SECRET por separado mediante ~/.gemini/settings.json.

VS Code (Copilot)

Abre la Paleta de Comandos (Cmd+Shift+P / Ctrl+Shift+P) > MCP: Add Server > selecciona Command (stdio).

O añádelo a .vscode/mcp.json en el directorio de tu proyecto:

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

Cursor

Añádelo a .cursor/mcp.json (a nivel de proyecto) o ~/.cursor/mcp.json (global):

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

Clientes compatibles

Este servidor MCP funciona con cualquier cliente que admita el Model Context Protocol, incluyendo:

{
  "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" }

Características

• 48 herramientas en 8 categorías que cubren toda la API de Spaceship
• 13 tipos de registros DNS con herramientas de creación dedicadas y seguras por tipo (A, AAAA, ALIAS, CAA, CNAME, HTTPS, MX, NS, PTR, SRV, SVCB, TLSA, TXT)
• Ciclo de vida completo del dominio — registrar, renovar, transferir y restaurar dominios
• Integración con SellerHub — listar dominios en venta y generar enlaces de pago
• Análisis de alineación DNS — comparar registros esperados vs. reales para detectar configuraciones incorrectas
• Privacidad WHOIS y gestión de contactos con soporte de atributos específicos por TLD
• Validación de entrada y salida mediante esquemas Zod en cada herramienta para operaciones seguras y predecibles
• 5 Recursos MCP para carga de contexto pasiva (lista de dominios, detalles de dominio, registros DNS, contactos, SellerHub)
• 9 Prompts MCP — 5 flujos de trabajo guiados y 4 con autocompletado de argumentos
• Suscripciones a recursos con detección de cambios basada en sondeo y notificaciones automáticas
• Caché de respuestas con TTL configurable e invalidación automática en escrituras
• Manejo de límites de tasa con retroceso exponencial y soporte de cabecera Retry-After
• Filtrado de conjuntos de herramientas para exponer solo las categorías de herramientas que necesitas
• Modo de carga dinámica de herramientas para agentes con ventanas de contexto limitadas
• Mensajes de error accionables con sugerencias de recuperación según el contexto
• Soporte Docker para despliegue en contenedores
• 453 pruebas unitarias con cobertura casi completa

Configuración

Requerido

Genera tus credenciales en el Administrador de API de Spaceship.

Opcional

Configuración de la clave de API

Crear tu clave de API

1. Inicia sesión en tu cuenta de Spaceship
2. Navega al Administrador de API (enlace directo)
3. Haz clic en Nueva clave de API
4. Dale a la clave un nombre descriptivo (por ejemplo, "Servidor MCP")
5. Selecciona los alcances que necesitas (consulta abajo)
6. Copia tanto la clave de API como el secreto de API — el secreto solo se muestra una vez

Alcances disponibles

Cada alcance controla el acceso a una parte específica de la API de Spaceship. Al crear tu clave, habilita solo los alcances que necesitas.

Alcances por característica

La tabla siguiente muestra qué alcances se requieren para cada grupo de herramientas.

Presets de alcance recomendados

Acceso completo — habilita todo para uso sin restricciones:

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

Solo gestión de DNS — solo lectura/escritura de registros DNS:

dnsrecords:read  dnsrecords:write

Solo lectura — navega por dominios y registros sin realizar cambios:

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

Herramientas disponibles

Registros DNS

Creación de registros específicos por tipo

Cada tipo de registro DNS tiene una herramienta dedicada con parámetros seguros por tipo y validación.

Gestión de dominios

Ciclo de vida del dominio

Contactos y privacidad

Servidores de nombres personales

SellerHub

Análisis

Recursos MCP

Los recursos proporcionan contexto pasivo que los clientes pueden cargar sin llamar a herramientas.

Los clientes que admiten suscripciones a recursos recibirán notificaciones automáticas cuando los datos cambien (sondeo cada 30 segundos).

Prompts MCP

Los prompts proporcionan flujos de trabajo guiados que los clientes pueden presentar como comandos de barra o acciones rápidas.

Flujos de trabajo guiados

Prompts de autocompletado

Estos prompts admiten autocompletado de argumentos para nombres de dominio y valores comunes:

Filtrado de conjuntos de herramientas

Reduce el uso de la ventana de contexto habilitando solo las categorías de herramientas que necesitas. Establece la variable de entorno SPACESHIP_TOOLSETS a una lista separada por comas:

SPACESHIP_TOOLSETS=dns,domains

Cuando no se establece, todos los conjuntos de herramientas están habilitados. Los nombres no válidos se ignoran; si todos los nombres son no válidos, todos los conjuntos de herramientas se habilitan como respaldo.

Carga dinámica de herramientas

Para agentes con ventanas de contexto limitadas, el modo dinámico reemplaza las 48 herramientas con 3 meta-herramientas ligeras:

SPACESHIP_DYNAMIC_TOOLS=true

Flujo de trabajo:

1. search_tools({ query: "dns" }) — descubrir herramientas relevantes
2. describe_tools({ tools: ["create_a_record"] }) — obtener el esquema completo de parámetros
3. execute_tool({ tool: "create_a_record", arguments: { ... } }) — ejecutar

Los recursos, prompts y completados permanecen disponibles en modo dinámico.

Notas de seguridad

• Modelo de confianza: Cualquier prompt o agente autorizado para llamar a este servidor MCP puede ejecutar acciones de la API de Spaceship con las credenciales configuradas.
• Credenciales de privilegio mínimo: Usa claves de API de Spaceship separadas por entorno/equipo/caso de uso y habilita solo los ámbitos que necesitas (ver Ámbitos disponibles).
• Aprobaciones para acciones de escritura: Habilita aprobaciones del lado del host para herramientas de mutación (register_domain, create_*, update_*, delete_*, save_*, set_* y operaciones de ciclo de vida).
• Gobernanza de configuración del equipo: Mantén la configuración MCP compartida en control de versiones, exige revisión para cambios en comando/args/env/filtrado de conjuntos de herramientas y guarda los secretos en un almacén o gestor de secretos del host (no en archivos de texto plano del repositorio).

Ejemplo de uso

Una vez conectado, puedes interactuar con la API de Spaceship usando lenguaje natural:

• "Lista todos mis dominios"
• "Comprueba si example.com está disponible para registro"
• "Crea un registro A para api.example.com apuntando a 203.0.113.10"
• "Configura registros MX para example.com para usar Google Workspace"
• "Activa la privacidad WHOIS en example.com"
• "Comprueba si mis registros DNS para example.com coinciden con lo esperado"
• "Lista mis dominios en venta en SellerHub"
• "Transfiere example.com a Spaceship"

Comunidad

• Soporte: SUPPORT.md
• Reporte de seguridad: SECURITY.md
• Guías de contribución: CONTRIBUTING.md
• Reportes de errores y solicitudes de funciones: Problemas

Desarrollo

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

Estructura del proyecto

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

Requisitos

• Node.js >= 20
• Una cuenta de Spaceship con credenciales de API

Licencia

MIT - ver LICENSE para más detalles.