Connect Turno to Claude

mkdir turno-mcp
cd turno-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod

{
  "name": "turno-mcp",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.22.0"
  }
}

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const TOKEN = process.env.TURNO_ACCESS_TOKEN;
const PARTNER_ID = process.env.TURNO_PARTNER_ID;
const BASE_URL =
  process.env.TURNO_BASE_URL || "https://sandbox.turnoverbnb.com/v2";

if (!TOKEN || !PARTNER_ID) {
  console.error("Missing TURNO_ACCESS_TOKEN or TURNO_PARTNER_ID");
  process.exit(1);
}

async function turnoGet(path, params = {}) {
  const url = new URL(`${BASE_URL}${path}`);
  for (const [key, value] of Object.entries(params)) {
    if (value !== undefined && value !== null && value !== "") {
      url.searchParams.append(key, String(value));
    }
  }

  const response = await fetch(url.toString(), {
    method: "GET",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      "TBNB-Partner-ID": PARTNER_ID,
      Accept: "application/json",
    },
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Turno API ${response.status}: ${body}`);
  }

  return response.json();
}

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

// Tool 1: List cleaning projects
server.tool(
  "list-projects",
  "List cleaning projects (turnovers) from Turno. Returns project id, status, schedule, property, assigned cleaner, and payment status. Use this first to find project ids.",
  {
    start: z.string().optional().describe("Start date, YYYY-MM-DD"),
    end: z.string().optional().describe("End date, YYYY-MM-DD"),
    properties: z
      .string()
      .optional()
      .describe("Comma-separated property ids to filter by"),
    cleaners: z
      .string()
      .optional()
      .describe("Comma-separated cleaner ids to filter by"),
    page: z.number().optional(),
    limit: z.number().optional(),
  },
  async (args) => {
    const data = await turnoGet("/projects", args);
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
);

// Tool 2: Get a project's checklist, including cleaner photos
server.tool(
  "get-project-checklist",
  "Fetch the checklist for a specific cleaning project. Each item includes its completion status, cleaner comment, whether a photo was required (image_required), the host's reference photo_url, and cleaner_images: the photo URLs the cleaner uploaded during the turnover.",
  {
    project_id: z
      .string()
      .describe("Turno project id (get from list-projects)"),
  },
  async ({ project_id }) => {
    const data = await turnoGet(`/projects/${project_id}/checklist`);
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
);

// Tool 3: List problem reports
server.tool(
  "list-problems",
  "List problem reports (damage, missing inventory, maintenance issues) raised through Turno, with title, description, resolved/unresolved status, attached image URLs, property, and reporting cleaner.",
  {
    property_id: z
      .string()
      .optional()
      .describe("Optional property id to filter by"),
    status: z
      .enum(["resolved", "unresolved"])
      .optional()
      .describe("Filter by resolution status"),
    page: z.number().optional(),
    limit: z.number().optional(),
  },
  async ({ property_id, status, page, limit }) => {
    const data = await turnoGet("/problems", {
      "property-id": property_id,
      status,
      page,
      limit,
    });
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
);

// Tool 4: List cleaners
server.tool(
  "list-cleaners",
  "List the cleaners (contractors) connected to this Turno account.",
  {},
  async () => {
    const data = await turnoGet("/contractors");
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
);

// Tool 5: List cleaner reviews
server.tool(
  "list-reviews",
  "List host reviews of completed cleanings: star rating, review text, cleaner, property, and project. Useful for cleaner performance analysis.",
  {
    start: z.string().optional().describe("Start date, YYYY-MM-DD"),
    end: z.string().optional().describe("End date, YYYY-MM-DD"),
    properties: z
      .string()
      .optional()
      .describe("Comma-separated property ids to filter by"),
  },
  async (args) => {
    const data = await turnoGet("/reviews", args);
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

~/Library/Application Support/Claude/claude_desktop_config.json

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "turno": {
      "command": "node",
      "args": ["/absolute/path/to/turno-mcp/index.js"],
      "env": {
        "TURNO_ACCESS_TOKEN": "your_oauth_access_token",
        "TURNO_PARTNER_ID": "your_tbnb_partner_id",
        "TURNO_BASE_URL": "https://sandbox.turnoverbnb.com/v2"
      }
    }
  }
}