Connect Key Data to Claude

mkdir keydata-mcp && cd keydata-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";

// Key Data issues both of these. The base URL is account-specific,
// which is why the public docs show it as a {{url}} variable.
const BASE_URL = process.env.KEYDATA_BASE_URL;
const API_KEY = process.env.KEYDATA_API_KEY;

if (!BASE_URL || !API_KEY) {
  console.error("Set KEYDATA_BASE_URL and KEYDATA_API_KEY first.");
  process.exit(1);
}

async function kd(method, path, body) {
  const res = await fetch(`${BASE_URL}${path}`, {
    method,
    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) throw new Error(`Key Data ${res.status}: ${await res.text()}`);
  return res.json();
}

const server = new McpServer({ name: "keydata", version: "1.0.0" });
const text = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });

server.tool(
  "get-session",
  "Confirm which Key Data tenant this API key belongs to and its reservation data provider. Run this first.",
  {},
  async () => text(await kd("GET", "/api/v1/pm/session"))
);

server.tool(
  "list-properties",
  "List property records with pagination. Returns property IDs, bedrooms, types, and activity status. Use this to discover property IDs for KPI queries.",
  {
    page: z.number().optional().describe("Page number, default 1"),
    limit: z.number().optional().describe("Records per page"),
    is_active: z.boolean().optional().describe("Filter to active properties"),
  },
  async ({ page = 1, limit = 100, is_active }) =>
    text(await kd("POST", "/api/v1/pm/properties", { page, limit, is_active }))
);

server.tool(
  "portfolio-kpis",
  "Aggregated portfolio-level KPIs (occupancy, ADR, RevPAR, and more) as a time series, with comparison periods. The main tool for portfolio health questions.",
  {
    timescale: z.enum(["Day", "Week", "Month"]).describe("Aggregation granularity"),
    start: z.string().describe("Range start, YYYY-MM-DD"),
    end: z.string().describe("Range end, YYYY-MM-DD"),
  },
  async ({ timescale, start, end }) =>
    text(await kd("POST", "/api/v1/pm/properties/portfolio", {
      timescale,
      primary_range: { start, end },
    }))
);

server.tool(
  "property-kpis",
  "Property-level KPI metrics for comparing units inside the portfolio.",
  {
    timescale: z.enum(["Day", "Week", "Month"]),
    start: z.string().describe("Range start, YYYY-MM-DD"),
    end: z.string().describe("Range end, YYYY-MM-DD"),
  },
  async ({ timescale, start, end }) =>
    text(await kd("POST", "/api/v1/pm/properties/kpis", {
      timescale,
      primary_range: { start, end },
    }))
);

server.tool(
  "market-kpis",
  "Market-level KPI metrics for benchmarking the portfolio against its market, with optional comparison periods.",
  {
    timescale: z.enum(["Day", "Week", "Month"]),
    start: z.string().describe("Range start, YYYY-MM-DD"),
    end: z.string().describe("Range end, YYYY-MM-DD"),
  },
  async ({ timescale, start, end }) =>
    text(await kd("POST", "/api/v1/pm/market/kpis", {
      timescale,
      primary_range: { start, end },
    }))
);

await server.connect(new StdioServerTransport());

{
  "mcpServers": {
    "keydata": {
      "command": "node",
      "args": ["/absolute/path/to/keydata-mcp/index.js"],
      "env": {
        "KEYDATA_BASE_URL": "https://your-issued-base-url",
        "KEYDATA_API_KEY": "your_key_here"
      }
    }
  }
}