Airbnb MCP Server

Un servidor alojado de Model Context Protocol (MCP) que ofrece a Claude, Cursor, Windsurf y cualquier otro cliente MCP dos herramientas de Airbnb de solo lectura. Busca estancias por ubicación y fechas, y lee un anuncio completo por completo, todo como JSON estructurado, sin cuenta de desarrollador de Airbnb ni aprobación de socio.

Lee páginas públicas de anuncios que un visitante sin sesión puede ver.

https://mcp.hasdata.com/api/mcp?apis=airbnb

Contenido

• Qué necesitas

• Inicio rápido

• Ejemplos de prompts

• Herramientas

• Errores y casos de fallo

• Precios, plan gratuito y límites

• Selección de herramientas

• Cómo se compara

• Preguntas frecuentes

• Enlaces de HasData

• Desarrollo

• Contribuciones

• Licencia

Related MCP server: lilo-vacation-rentals

Qué necesitas

Un cliente MCP y una clave de API de HasData desde el panel de control, que se crea gratis y sin tarjeta; la prueba cubre unas 200 llamadas a la tarifa de 5 créditos. Es un servidor remoto, así que el camino más sencillo es una URL y una cabecera x-api-key, sin contenedor que ejecutar y sin cuenta de desarrollador de Airbnb en ningún paso del proceso. Un cliente que solo hable stdio lo alcanza mediante un lanzador ligero, publicado como @hasdata/airbnb-mcp en npm y hasdata-airbnb-mcp en PyPI, que se muestra abajo.

Inicio rápido

La URL del servidor es la misma para todos los clientes. Lo usamos de forma práctica en Claude Code y Claude Desktop. El resto de bloques siguen el formato documentado de cada cliente para un servidor remoto.

Los clientes con soporte de OAuth pueden añadir la misma URL como conector e iniciar sesión sin poner una clave en un archivo de configuración.

claude mcp add --transport http airbnb "https://mcp.hasdata.com/api/mcp?apis=airbnb" \
  --header "x-api-key: HASDATA_API_KEY"

Ve a Configuración, luego Conectores, luego Añadir conector personalizado, pega https://mcp.hasdata.com/api/mcp?apis=airbnb e inicia sesión.

Para la vía del archivo de configuración, Claude Desktop solo carga servidores locales (stdio), así que accede a un servidor remoto mediante un lanzador stdio. El paquete @hasdata/airbnb-mcp es ese lanzador, y lee la clave del entorno. Añade esto a claude_desktop_config.json:

{
  "mcpServers": {
    "airbnb": {
      "command": "npx",
      "args": ["-y", "@hasdata/airbnb-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

Si usas Python en lugar de Node, sustituye el lanzador por el paquete de PyPI, que uvx ejecuta sin instalación manual:

{
  "mcpServers": {
    "airbnb": {
      "command": "uvx",
      "args": ["hasdata-airbnb-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

~/.cursor/mcp.json para todos los proyectos, o .cursor/mcp.json para uno solo:

{
  "mcpServers": {
    "airbnb": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=airbnb",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

~/.codeium/windsurf/mcp_config.json. Windsurf llama al campo serverUrl, no url:

{
  "mcpServers": {
    "airbnb": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=airbnb",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

.vscode/mcp.json en el espacio de trabajo:

{
  "servers": {
    "airbnb": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=airbnb",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

Ejemplos de prompts

Son prompts, no código. Pega uno y el agente elige la herramienta por sí mismo. Cada uno está anotado con las llamadas que requiere, porque cada llamada correcta cuesta 5 créditos.

Busca estancias en Austin para dos adultos del 15 al 18 de septiembre y dame las diez mejor valoradas por menos de 200 $ la noche.

Una llamada, 5 créditos. La valoración y el precio por noche vienen en el resultado de búsqueda.

Toma el primer resultado y extrae todos sus servicios, el número de huéspedes y dormitorios, y los datos del anfitrión.

Una llamada, 5 créditos. Esos datos están en la página del anuncio, que la herramienta de detalles lee por URL.

Compara el precio por noche de una estancia de tres noches para dos huéspedes en Austin con Nashville.

Dos llamadas, 10 créditos, una búsqueda por ciudad.

Para esta URL de anuncio, dime cuántas camas y baños tiene y si el anfitrión es Superhost.

Una llamada, 5 créditos.

Un resultado de búsqueda es intencionadamente ligero, suficiente para clasificar y preseleccionar. Los servicios, las camas, el anfitrión y la descripción completa llegan con la llamada al anuncio, así que un prompt que preselecciona y luego inspecciona tres alojamientos son una búsqueda más tres llamadas al anuncio.

Herramientas

Dos herramientas, de solo lectura. Las muestras siguientes están recortadas de llamadas reales, y los números cambian con las actualizaciones de Airbnb. Fíjate en su forma. Cada nombre de herramienta enlaza a su referencia de endpoint, que incluye la lista completa de campos.

Las muestras son el payload, no la respuesta completa. Un resultado de tools/call contiene un bloque de texto, y ese texto es a su vez JSON que contiene url, status, text y json, con los datos extraídos en json. En una respuesta JSON-RPC cruda, la ruta es result.content[0].text, parseado, y luego .json. Un cliente de chat te lo desempaqueta, y el código que habla directamente con el endpoint no.

Obtener anuncios de Airbnb

hasdata_airbnb_listing_getAirbnbListings

Una página de resultados de búsqueda por ubicación y fechas.

Devuelve un array properties y pagination, cuyos nextPageToken y pageTokens recorren el conjunto de resultados. Cada propiedad incluye id, url, title, latitude, longitude, una breve description a modo de eslogan, un array photos, rating, reviews, un array badges como Guest favorite o Superhost, y un objeto price. price contiene originalPrice, un discountedPrice opcional cuando la estancia tiene descuento, un qualifier como for 3 nights, y un breakdown.

Un resultado de búsqueda es intencionadamente ligero. Las camas, los baños, los servicios, el anfitrión y la descripción completa no están aquí; vienen de la herramienta de propiedad que aparece abajo. No esperes un recuento de dormitorios en un resultado de búsqueda.

{
  "id": "17545365",
  "url": "https://www.airbnb.com/rooms/17545365",
  "title": "Home in East Austin",
  "latitude": 30.25741,
  "longitude": -97.73366,
  "description": "Downtown Casa - neighborhood feel, close to it all",
  "rating": 4.87,
  "reviews": 601,
  "badges": ["Guest favorite"],
  "price": {
    "originalPrice": "$607",
    "discountedPrice": "$447",
    "qualifier": "for 3 nights",
    "breakdown": [{ "description": "3 nights x $149.00", "price": "$447.00" }]
  }
}

Obtener detalles de la propiedad de Airbnb

hasdata_airbnb_property_getAirbnbPropertyDetails

Un anuncio completo, a partir de su URL.

Devuelve title, un array overview como ["4 guests", "2 bedrooms", "2 beds", "2 baths"], la description completa, rating, reviews, address, latitude, longitude, un array photos, guestCapacity, un objeto host, un array amenities y safetyAndPropertyInfo. El objeto host incluye name, isSuperhost, isVerified, los reviews propios del anfitrión, rating y yearsHosting. Cada servicio incluye un title, un type, una description opcional y un indicador available, así que un filtro debe leer available; no asumas que todos los servicios listados están presentes.

{
  "id": "17545365",
  "title": "Downtown Casa - neighborhood feel, close to it all",
  "overview": ["4 guests", "2 bedrooms", "2 beds", "2 baths"],
  "rating": 4.87,
  "reviews": 601,
  "address": "Austin, Texas, United States",
  "guestCapacity": 4,
  "host": { "name": "Deanna", "isSuperhost": true, "isVerified": true, "reviews": 1273, "rating": 4.86, "yearsHosting": 11 },
  "amenities": [
    { "title": "Wifi", "type": "SYSTEM_WI_FI", "available": true },
    { "title": "Free washer – In unit", "type": "SYSTEM_WASHER", "available": true }
  ]
}

Errores y casos de fallo

Tu cliente casi nunca ve un código de error HTTP en una llamada a una herramienta. La capa MCP responde 200 y coloca el fallo dentro del resultado, con isError establecido a true y el motivo como texto. El agente lee un mensaje donde cabría esperar una línea de estado.

Una clave incorrecta aparece como salida de la herramienta, no como una conexión fallida. tools/list acepta cualquier clave no vacía y devuelve ambas herramientas, así que el cliente completa el handshake y se muestra en verde. La primera llamada a una herramienta devuelve entonces isError: true y el texto HasData API error: 401 Unauthorized. Estate atento a esa cadena, porque nada anterior en el flujo informa del problema.

Una clave ausente es el único error HTTP real. La autorización se ejecuta antes que cualquier herramienta, y la propia conexión falla con 401. Las cabeceras CORS están presentes, y un cliente de navegador lee el estado en lugar de un fallo de red opaco.

Un argumento que incumple el esquema de una herramienta se rechaza antes de que se convierta en un scraping. El servidor responde con isError: true y el texto MCP error -32602: Input validation error, indicando el campo infractor. No se obtiene nada y no se cobra nada.

Una búsqueda sin disponibilidad devuelve un resultado correcto con un array properties vacío, no un error. Una ubicación y un rango de fechas sin nada disponible siguen devolviendo requestMetadata.status establecido a ok. Comprueba la longitud del array antes de iterar.

Un anuncio que ha sido retirado devuelve 400 con requestMetadata.status establecido a error. Una URL de una búsqueda antigua puede apuntar a un alojamiento que ya no existe.

Los resultados que incluyen datos también llevan un requestMetadata.id que conviene citar al contactar con el soporte.

Precios, plan gratuito y límites

Cada herramienta de Airbnb cuesta 5 créditos por llamada correcta. El tamaño de la respuesta no cambia el precio. Una página de búsqueda con decenas de estancias cuesta lo mismo que una con dos.

La prueba gratuita es de 1.000 créditos durante 30 días sin tarjeta, lo que equivale a 200 llamadas de Airbnb. Después, una cuenta activa sigue recibiendo 100 créditos cada día siempre que su saldo baje de 100, así que un agente de bajo volumen funciona con el plan gratuito de forma indefinida.

Los planes de pago empiezan en 49 $ al mes por 200.000 créditos, es decir, 40.000 llamadas. El precio unitario baja con el volumen: de 1,23 $ por cada 1.000 llamadas en el plan inicial a 0,50 $ en Business, 0,42 $ en Growth y 0,37 $ en los planes de alto volumen más grandes.

Tu plan también fija la concurrencia. La prueba gratuita permite 1 solicitud a la vez; Startup 15, Business 30, Growth 50, y los planes de alto volumen van de 200 a 1.500. Gestiona el caso de desbordamiento de forma defensiva en cualquier proceso desatendido.

Una solicitud que devuelve un código distinto de 200 no se factura. Una llamada correcta que no encuentra nada sigue siendo una llamada.

Selección de herramientas

El parámetro de consulta apis decide qué herramientas ve tu agente. Menos herramientas significa menos contexto dedicado a las definiciones de herramientas y menos probabilidades de que el modelo elija la equivocada.

?apis=airbnb                     the two tools in this repo
?apis=airbnb,booking             add Booking.com stays
?apis=airbnb,google_maps         add Google Maps places

El parámetro acepta nombres de proveedor como airbnb y nombres de API individuales como airbnb_listing. Los nombres mal escritos se ignoran. Si todos los nombres son incorrectos, la solicitud falla con 400 y el cuerpo indica tanto lo que no reconoció como todos los valores válidos. Si omites el parámetro, el mismo endpoint expone las 57 herramientas de HasData.

Cómo se compara

Airbnb no tiene una API pública de búsqueda. Su programa de API es una integración para socios y coanfitriones pensada para gestionar tus propios anuncios, no una forma de leer el mercado. Para buscar estancias y leer anuncios arbitrarios, la única vía es hacer scraping de las páginas públicas, y este servidor lo hace bajo un esquema estable.

Lo que este servidor no hace. Ni reservas, ni mensajería, ni panel de control del anfitrión, ni datos de huéspedes. Lee lo que un visitante sin sesión iniciada puede ver.

FAQ

¿Existe un servidor MCP oficial de Airbnb?

Airbnb no publica ninguno. Este está mantenido por HasData y lee páginas públicas, por lo que no necesita ninguna cuenta de desarrollador de Airbnb.

¿Qué es un servidor MCP de Airbnb?

Es un servidor que expone los datos de Airbnb como herramientas que un cliente de IA puede invocar. El cliente envía una llamada a una herramienta a través del Model Context Protocol, el servidor obtiene los datos y devuelve JSON estructurado, y el modelo trabaja con el resultado. Este expone dos herramientas y se ejecuta de forma remota.

¿Necesito una clave de API de Airbnb o una cuenta de socio?

No. La única credencial es tu clave de HasData. No hay proceso de incorporación de socios, porque las herramientas leen páginas públicas de Airbnb.

¿Por qué el resultado de búsqueda no muestra camas o servicios?

Porque Airbnb no los incluye en la tarjeta de búsqueda. Están en la página del alojamiento, que la herramienta de detalles lee mediante la URL. Busca para preseleccionar y luego llama a la herramienta del alojamiento para obtener más detalle.

¿Puedo filtrar por huéspedes, mascotas o fechas?

Sí. La herramienta de anuncios acepta checkIn, checkOut y los recuentos de adults, children, infants y pets, y devuelve la disponibilidad y los precios para ese grupo y ese período.

¿Puedo usar esto junto con otras APIs de HasData?

Sí. El parámetro apis acepta una lista, y ?apis=airbnb,booking le da a tu agente Airbnb más Booking.com. Omite el parámetro y obtendrás todo.

Cumplimiento normativo y datos personales

HasData solo accede a datos disponibles públicamente. Los términos de una plataforma pueden restringir el acceso automatizado, y tú eres responsable de tu propio cumplimiento normativo. Si los datos que recopilas incluyen información personal, asegúrate de tener una base legal para ello según el GDPR, la CCPA o las normas equivalentes de tu jurisdicción.

Enlaces de HasData

Desarrollo

Este repositorio es la configuración y la documentación de un servidor remoto. No hay paso de compilación ni nada que contenerizar.

Las pruebas en test/ verifcan el contrato de las herramientas, la parte que puede romperse sin que haya un commit en este repositorio. Comprueban que ?apis=airbnb devuelve exactamente dos herramientas, que cada herramienta sigue declarando sus parámetros obligatorios, que ningún nombre ha cambiado y que la clave en uso es realemente aceptada. Esa últmia comprobación llama a una herramienta de verdad y cuesta 5 créditos, que es el preciio de un canario que puede fallar por la razón correcta.

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

# Windows PowerShell
$env:HASDATA_API_KEY="your_key_here"; npm test

La misma suite se ejecuta en CI en cada push y una vez por semana de forma programada, por que la lista de herramientas upstream puede cambiar sin que nadie toque este repositorio. Un fallo signifca que la lista de herramientas se ha movido, que la clave ha dejado de funcionar o que el endpoint no era accesible, y el mensaje de la aserción indiica cuál de esos casos es.

Contribuciones

Las correcciones de las tablas de herramientas y de los ejemplos de respuesta son la contribución más útil, por que son las partes que tienden a desactualizarse. Incluye la llamada que hiciste y la respuesta que obtuviste. Las pull requests de forks ejecutan la suite sin clave, y las comprobaciones en vivo se omiten en lugar de ponerse en rojo.

Licencia

MIT. Consula LICENSE.