Connect Minut to Claude

mkdir minut-mcp && cd minut-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 BASE = "https://api.minut.com/v8";
const CLIENT_ID = process.env.MINUT_CLIENT_ID;
const CLIENT_SECRET = process.env.MINUT_CLIENT_SECRET;

if (!CLIENT_ID || !CLIENT_SECRET) {
  console.error("Set MINUT_CLIENT_ID and MINUT_CLIENT_SECRET first.");
  process.exit(1);
}

// Minut tokens are short-lived (~1h). Re-mint 5 minutes before expiry,
// per Minut's "schedule a refresh rather than waiting for 401s" guidance.
let token = null;
let tokenExp = 0;

async function getToken() {
  const now = Date.now();
  if (token && now < tokenExp) return token;
  const res = await fetch(`${BASE}/oauth/token`, {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: "Basic " +
        Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64"),
    },
    body: "grant_type=client_credentials&response_type=token",
  });
  if (!res.ok) throw new Error(`Minut token request failed (${res.status})`);
  const data = await res.json();
  token = data.access_token;
  tokenExp = now + (data.expires_in - 300) * 1000;
  return token;
}

async function get(path, params = {}) {
  const url = new URL(`${BASE}${path}`);
  for (const [k, v] of Object.entries(params)) {
    if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v));
  }
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${await getToken()}` },
  });
  if (!res.ok) throw new Error(`Minut ${res.status}: ${await res.text()}`);
  return res.json();
}

const json = (d) => ({ content: [{ type: "text", text: JSON.stringify(d, null, 2) }] });

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

server.registerTool(
  "list_organizations",
  {
    description: "List the Minut organizations this account belongs to. Call first to get the organization_id other tools need.",
    inputSchema: {},
  },
  async () => json(await get("/organizations"))
);

server.registerTool(
  "list_homes",
  {
    description: "List all homes (monitored properties) in an organization.",
    inputSchema: {
      organization_id: z.string().describe("Minut organization id (from list_organizations)"),
    },
  },
  async ({ organization_id }) =>
    json(await get(`/organizations/${organization_id}/homes`))
);

server.registerTool(
  "list_devices",
  {
    description: "List sensors in an organization. Filter to offline or low-battery devices for a health check.",
    inputSchema: {
      organization_id: z.string().describe("Minut organization id"),
      offline: z.boolean().optional().describe("true = only devices currently offline"),
      low_battery: z.boolean().optional().describe("true = only devices low on battery"),
    },
  },
  async ({ organization_id, offline, low_battery }) =>
    json(await get(`/organizations/${organization_id}/devices`, { offline, low_battery }))
);

server.registerTool(
  "get_device",
  {
    description: "Get one device, including latest_sensor_values (sound, temperature, humidity). Devices sync at least once per hour, so these are near-real-time, not live.",
    inputSchema: { device_id: z.string().describe("Minut device id") },
  },
  async ({ device_id }) => json(await get(`/devices/${device_id}`))
);

server.registerTool(
  "get_home_events",
  {
    description: "List events for a home: noise_detected, noise_ongoing, noise_quieted, disturbance_first_notice through disturbance_third_notice, crowd_detected, smoking_detected, tamper_removed, battery_low, device_offline, and more. Page with limit/offset.",
    inputSchema: {
      home_id: z.string().describe("Minut home id (from list_homes)"),
      event_type: z.string().optional().describe("Comma-separated event types to include"),
      start_at: z.string().optional().describe("ISO-8601 UTC start, e.g. 2026-06-01T00:00:00Z"),
      end_at: z.string().optional().describe("ISO-8601 UTC end"),
      limit: z.number().optional().describe("Page size, default 50"),
      offset: z.number().optional().describe("Rows to skip, for paging"),
    },
  },
  async ({ home_id, ...params }) =>
    json(await get(`/homes/${home_id}/events`, { limit: 50, ...params }))
);

server.registerTool(
  "get_sound_levels",
  {
    description: "Decibel time series for a device. Defaults to the last 4 hours if no start_at. Use time_resolution (seconds) to bucket, include_min_max for peaks.",
    inputSchema: {
      device_id: z.string().describe("Minut device id"),
      start_at: z.string().optional().describe("ISO-8601 start (default: 4 hours ago)"),
      end_at: z.string().optional().describe("ISO-8601 end"),
      time_resolution: z.number().optional().describe("Bucket size in seconds, e.g. 300"),
      include_min_max: z.boolean().optional().describe("Include min/max per bucket"),
    },
  },
  async ({ device_id, ...params }) =>
    json(await get(`/devices/${device_id}/sound_level`, { include_min_max: true, ...params }))
);

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

{
  "mcpServers": {
    "minut": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/minut-mcp/index.js"],
      "env": {
        "MINUT_CLIENT_ID": "your-client-id",
        "MINUT_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

claude mcp add \
  --env MINUT_CLIENT_ID=your-client-id \
  --env MINUT_CLIENT_SECRET=your-client-secret \
  --transport stdio minut \
  -- node /ABSOLUTE/PATH/TO/minut-mcp/index.js

List our homes and devices, and flag anything offline or low on battery.

Pull noise and disturbance events for every home over the last 30 days
and rank homes by number of disturbance notices.

Get the sound levels for the loudest home's device last weekend in
10-minute buckets and tell me when it peaked.