Connect Hostfully to Claude

mkdir hostfully-mcp && cd hostfully-mcp
npm init -y
npm pkg set type="module"
npm install @modelcontextprotocol/sdk zod

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const API_BASE = "https://api.hostfully.com/api/v3.3";
const API_KEY = process.env.HOSTFULLY_API_KEY;
const AGENCY_UID = process.env.HOSTFULLY_AGENCY_UID;

if (!API_KEY || !AGENCY_UID) {
  console.error("Set HOSTFULLY_API_KEY and HOSTFULLY_AGENCY_UID first.");
  process.exit(1);
}

// Authenticated GET. The API key rides in a header on every request.
async function get(path) {
  const res = await fetch(`${API_BASE}${path}`, {
    headers: { "X-HOSTFULLY-APIKEY": API_KEY, Accept: "application/json" },
  });
  if (!res.ok) throw new Error(`Hostfully ${res.status}: ${await res.text()}`);
  return res.json();
}

function json(data) {
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
}

const server = new McpServer({ name: "hostfully", version: "1.0.0" });

server.registerTool(
  "list_properties",
  {
    description: "List the properties in the Hostfully agency.",
    inputSchema: {
      limit: z.number().optional().describe("Max rows per page, 1-100, default 100"),
      cursor: z.string().optional().describe("nextCursor from a previous page"),
    },
  },
  async ({ limit, cursor }) => {
    const q = new URLSearchParams({ agencyUid: AGENCY_UID, _limit: String(limit ?? 100) });
    if (cursor) q.set("_cursor", cursor);
    return json(await get(`/properties?${q}`));
  }
);

server.registerTool(
  "get_property",
  {
    description: "Get full details for one property by its UID.",
    inputSchema: { propertyUid: z.string().describe("Hostfully property UID") },
  },
  async ({ propertyUid }) => json(await get(`/properties/${propertyUid}`))
);

server.registerTool(
  "list_leads",
  {
    description: "List bookings (Hostfully calls them leads), optionally filtered by property or check-in date range.",
    inputSchema: {
      propertyUid: z.string().optional().describe("Limit to one property"),
      checkInFrom: z.string().optional().describe("Earliest check-in, YYYY-MM-DD"),
      checkInTo: z.string().optional().describe("Latest check-in, YYYY-MM-DD"),
      limit: z.number().optional().describe("Max rows per page, 1-100, default 100"),
      cursor: z.string().optional().describe("nextCursor from a previous page"),
    },
  },
  async ({ propertyUid, checkInFrom, checkInTo, limit, cursor }) => {
    const q = new URLSearchParams({ _limit: String(limit ?? 100) });
    if (propertyUid) q.set("propertyUid", propertyUid);
    else q.set("agencyUid", AGENCY_UID);
    if (checkInFrom) q.set("checkInFrom", checkInFrom);
    if (checkInTo) q.set("checkInTo", checkInTo);
    if (cursor) q.set("_cursor", cursor);
    return json(await get(`/leads?${q}`));
  }
);

server.registerTool(
  "get_lead",
  {
    description: "Get one booking (lead) by its UID, including check-in, check-out, and guest.",
    inputSchema: { leadUid: z.string().describe("Hostfully lead UID") },
  },
  async ({ leadUid }) => json(await get(`/leads/${leadUid}`))
);

server.registerTool(
  "list_orders",
  {
    description: "List financial orders for one property (get the propertyUid from list_properties first).",
    inputSchema: { propertyUid: z.string().describe("Hostfully property UID") },
  },
  async ({ propertyUid }) => {
    const q = new URLSearchParams({ propertyUid });
    return json(await get(`/orders?${q}`));
  }
);

server.registerTool(
  "list_guests",
  {
    description: "List all guests in the agency.",
    inputSchema: {},
  },
  async () => json(await get(`/guests/${AGENCY_UID}`))
);

const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Hostfully MCP server running on stdio");

{
  "mcpServers": {
    "hostfully": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/hostfully-mcp/index.js"],
      "env": {
        "HOSTFULLY_API_KEY": "your-api-key",
        "HOSTFULLY_AGENCY_UID": "your-agency-uid"
      }
    }
  }
}

claude mcp add \
  --env HOSTFULLY_API_KEY=your-api-key \
  --env HOSTFULLY_AGENCY_UID=your-agency-uid \
  --transport stdio hostfully \
  -- node /ABSOLUTE/PATH/TO/hostfully-mcp/index.js

Which bookings check in over the next 7 days? Group them by property.

How many properties do we manage, and which look inactive?

Pull the orders for the lake house and total the revenue this month.