# gingr-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives Claude **read-only** access to your [Gingr](https://www.gingrapp.com/) pet-care facility data — owners, animals, reservations, appointments, services, and staff. Ask Claude things like *"What was our daycare occupancy last week?"* or *"Which customers board most often?"* and it can pull the answer straight from your Gingr account.

> **Read-only by design.** This server never creates, edits, or deletes anything in Gingr.

## Tools

| Tool | What it does |
|---|---|
| `gingr_list_owners` | List pet owners (customers) — names, contact, signup dates |
| `gingr_list_animals` | List animals — species, breed, age, owner |
| `gingr_list_reservations` | Boarding/daycare reservations by date range |
| `gingr_get_owner_reservations` | All reservations for one owner (history / LTV) |
| `gingr_list_appointments` | Grooming / training / spa / bath appointments |
| `gingr_list_services` | Services offered, with prices |
| `gingr_list_employees` | Staff / employees |

## Prerequisites

- **Node.js 18+**
- Your **Gingr subdomain** (the `mybiz` in `https://mybiz.gingrapp.com`)
- A **Gingr API key** — in Gingr go to **Reports & More → Users → Edit User → API Keys** and create one.

## Install

Pick whichever is more convenient:

- **Option A — One-click (Claude Desktop):** download the `.mcpb` extension, double-click, fill in the form. No terminal, no config files. Best if you're not technical.
- **Option B — npm (any MCP host):** add a few lines to your client's config. Works with Claude Desktop, Claude Code, Cursor, and other MCP clients.

Either way you'll need your Gingr **subdomain** and **API key** (see [Prerequisites](#prerequisites)).

### Option A — One-click Desktop Extension (Claude Desktop)

1. Download **`gingr-mcp.mcpb`** from the [latest release](https://github.com/shashicandev/gingr-mcp/releases).
2. Double-click it (or in Claude Desktop: **Settings → Extensions → Install Extension…**).
3. When prompted, enter your **Gingr Subdomain** and **API Key**, then click **Install**.

The API key is stored securely in your OS keychain and never leaves your machine.

### Option B — npm

#### Claude Desktop

Add this to your `claude_desktop_config.json`
(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`,
Windows: `%APPDATA%\Claude\claude_desktop_config.json`), then restart Claude Desktop:

```json
{
  "mcpServers": {
    "gingr": {
      "command": "npx",
      "args": ["-y", "gingr-mcp"],
      "env": {
        "GINGR_SUBDOMAIN": "yourbiz",
        "GINGR_API_KEY": "your-api-key"
      }
    }
  }
}
```

#### Claude Code

```bash
claude mcp add gingr \
  --env GINGR_SUBDOMAIN=yourbiz \
  --env GINGR_API_KEY=your-api-key \
  -- npx -y gingr-mcp
```

`npx -y gingr-mcp` downloads and runs the latest version on demand — no global install needed.

## Configuration

| Variable | Required | Description |
|---|---|---|
| `GINGR_SUBDOMAIN` | yes | `mybiz`, `mybiz.gingrapp.com`, or a full `https://…` URL |
| `GINGR_API_KEY` | yes | A Gingr API key with read access |

## Tips

- Keep reservation/appointment date ranges to **≤ 30 days** — very wide ranges can time out on Gingr's side.
- Dates are `YYYY-MM-DD`.

## Local development

```bash
cd gingr-mcp
npm install
npm run build
npm test

# Inspect/run with the MCP Inspector
GINGR_SUBDOMAIN=yourbiz GINGR_API_KEY=your-api-key npm run inspector
```

## Releasing

Maintainer? See [RELEASING.md](RELEASING.md) for how to publish the npm package and build the `.mcpb` bundle.

## License

MIT © Canisys