# kickserv-mcp

**An MCP server for [Kickserv](https://www.kickserv.com) field service management — lets AI agents (Claude, ChatGPT, and any MCP-compatible client) read and manage customers, jobs, and invoices.**

Ask your AI assistant things like:

> "Which invoices are overdue and who do I need to call?"
> "Create a job for Kelly Nakamura — toilet rebuild, estimate $265."
> "What's my active job pipeline worth right now?"

Zero dependencies. Plain Node 18+. Nothing to install.

## Quick start (demo / mock mode)

```bash
node src/index.js
```

With no credentials set, the server runs in **mock mode** — a realistic sample plumbing-company dataset — so you can demo the full agent experience without touching a live account.

### Connect to Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kickserv": {
      "command": "node",
      "args": ["/absolute/path/to/kickserv-mcp/src/index.js"]
    }
  }
}
```

Restart Claude Desktop and ask: *"What's in my Kickserv account?"*

## Live mode

```bash
export KICKSERV_ACCOUNT=your-account-slug
export KICKSERV_API_TOKEN=your-api-token
node src/index.js
```

Live mode targets Kickserv's REST API using HTTP Basic auth with your API token. Verify endpoint paths against your account's [developer docs](https://help.kickserv.com/article/4-developer-api) before production use.

## Tools

| Tool | What it does |
|---|---|
| `list_customers` | List/search customers by name, contact, email, or address |
| `get_customer` | Full detail for one customer |
| `list_jobs` | List jobs, filter by status or customer |
| `get_job` | Full detail for one job |
| `create_job` | Create a new job for a customer |
| `list_invoices` | List invoices, filter by status (open/paid/overdue) or customer |
| `revenue_snapshot` | Open, overdue, and paid totals + active job pipeline value |

## Tests

```bash
npm test
```

Spawns the server over stdio and exercises the full protocol: initialize → tools/list → tool calls. 8 checks.

## Why this exists

AI agents are becoming the interface to business software. Field service platforms that agents can't talk to will lose deals to ones they can. This server is a working demonstration of what "agent-ready" looks like for a field service product — built as a portfolio piece by [Will Brownfield](mailto:willbrownfield@icloud.com), who builds MCP integrations for SaaS companies.

**Want your product to be agent-ready? Email me: willbrownfield@icloud.com**

## License

MIT