Gazelle MCP (unofficial)
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Gazelle MCP (unofficial)
Unofficial, community project. Not made by, affiliated with, endorsed by, or supported by Gazelle. Please don't contact Gazelle support about it; open an issue here instead.
An unofficial MCP server that connects Claude (Claude Desktop, Claude Code, or any MCP client) to your Gazelle account, the business platform for piano technicians.
Ask Claude things like:
"What appointments do I have next week in Springfield?"
"Build my 2026 mileage log as a CSV for my accountant."
"How many visits and how much billed work did I do in each state this year?"
"Add a note to Tuesday's appointment with the Smiths: replaced two bass strings."
It runs locally on your computer, talks to Gazelle using your own API credentials, and keeps its caches and logs in a local data/ folder.
Not tax advice. Mileage and jurisdiction output is informational. Review it, and check with a tax professional before filing.
Tools
Tool | What it does |
| Appointments in a date range, filterable by client name and status ( |
| One appointment by id, including service items and quoted value. |
| Clients, optionally filtered by name. |
| A per-trip business mileage log (home → each stop in time order → home, per day) with real driving distances, business purpose, and client, plus an estimated standard-mileage deduction. Optional CSV. |
| Visits, distinct clients, quoted service value, and tips per state (or state + city), to gauge where you may have filing obligations. |
| Local only. Records a correction (actual amount charged, tip received, reason) in |
| Recent changes made by this server. |
| Writes to Gazelle. Off by default. Appends text to an appointment's notes. |
| Writes to Gazelle. Off by default. Changes one service item's price on an appointment (e.g. to $0 for a no-charge visit). |
About the write tools
The server is read-only unless you set GAZELLE_ENABLE_WRITES=1. When enabled, every write:
Shows a preview and changes nothing unless called again with
confirm=true(Claude will ask you first).Re-reads the appointment afterwards and reports anything that changed besides what was asked.
set_service_item_priceautomatically restores the original items if anything unexpected changed.Is recorded in
data/audit-log.jsonl.
Gazelle's API can do far more (delete records, change billing, and so on). This server deliberately exposes only these two narrow edits.
Related MCP server: Jobber MCP Connector
Requirements
A Gazelle account with your business data.
A free Gazelle developer account (separate from your regular Gazelle login). See step 2.
Node.js 22.9 or newer (nodejs.org). Check with
node --version.Git, or download this repository as a ZIP from GitHub.
An MCP client such as Claude Desktop or Claude Code.
Setup
1. Download and build
git clone https://github.com/clirette/gazelle-mcp.git
cd gazelle-mcp
npm install
npm run build2. Create a Gazelle developer account
Gazelle's API uses OAuth: you register an "Integration" (an app) once, then authorize it to read your business account.
Go to https://gazelleapp.io/developer/signup and create a developer account (website, email, name, password). Gazelle requires your real name and email and deletes anonymous accounts.
Log in at https://gazelleapp.io/developer/login.
Gazelle's developer documentation is at https://gazelleapp.io/developer. Gazelle doesn't provide support for using the API beyond those docs, and this project is unofficial, so please report problems in this project's issues, not to Gazelle.
3. Register an Integration
In the developer portal, create a new Integration:
Name: anything, e.g.
My Gazelle MCP.Redirect URL:
https://localhost:8976/callbackGazelle requires an HTTPS redirect URL. Nothing needs to be running at that address: the next step explains how the code is captured. You can edit the URL later.
When you save, Gazelle shows an application id (also called the client id) and a secret. Copy the secret right away: Gazelle shows it only once and can't recover it.
4. Configure .env
Copy the example file and fill it in:
cp .env.example .env # Windows PowerShell: Copy-Item .env.example .envGAZELLE_CLIENT_ID=your-application-id
GAZELLE_CLIENT_SECRET=your-secret
# Where your workday starts and ends, for the mileage log
GAZELLE_HOME_STREET=123 Main St
GAZELLE_HOME_CITY=Springfield
GAZELLE_HOME_STATE=IL
GAZELLE_HOME_ZIP=62701
GAZELLE_TIMEZONE=America/Chicago
# Optional: enable the two tools that edit Gazelle
# GAZELLE_ENABLE_WRITES=1.env holds your secret. It's gitignored, so never commit or share it.
5. Authorize (one time)
npm run authThe script prints a link. Open it, log in to your Gazelle business account, and approve access.
Your browser then tries to open
https://localhost:8976/callback?code=...and shows an error page. That is expected.Copy the full URL from the address bar and paste it into the terminal. The code expires after 10 minutes.
The token is saved to data/token.json and refreshed automatically. Access tokens last 30 days. If the server isn't used for 90 days, Gazelle revokes the token and you'll need to run npm run auth again.
If data/localhost.pfx exists, npm run auth serves the callback over HTTPS and captures the code itself. You need a certificate your browser trusts for localhost:
With mkcert:
mkcert -install, thenmkcert -pkcs12 -p12-file data/localhost.pfx localhost, and setGAZELLE_AUTH_PFX_PASSWORD=changeit(mkcert's default).With the .NET SDK:
dotnet dev-certs https --trust, thendotnet dev-certs https -ep data/localhost.pfx -p gazelle-local.
6. Connect it to Claude
Use absolute paths to your copy of the repository. On Windows, use forward slashes (C:/Users/you/gazelle-mcp/...).
Claude Code:
claude mcp add --scope user gazelle -- node --env-file=/path/to/gazelle-mcp/.env /path/to/gazelle-mcp/dist/index.jsClaude Desktop: open Settings → Developer → Edit Config (or edit claude_desktop_config.json directly: %APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS) and add:
{
"mcpServers": {
"gazelle": {
"command": "node",
"args": [
"--env-file=/path/to/gazelle-mcp/.env",
"/path/to/gazelle-mcp/dist/index.js"
]
}
}
}Restart Claude Desktop. Then ask: "List my Gazelle appointments for this week."
Configuration
All settings are environment variables, usually set in .env.
Variable | Default | Purpose |
| (required) | From your Gazelle Integration. |
| (none) | Start/end point of each day's trips. Can also be passed to |
|
| Fallback timezone for dating trips. Gazelle stores a timezone per appointment, which takes precedence. |
| off |
|
| public OSRM demo server | Routing server for driving distances. Point it at a self-hosted OSRM for privacy or volume. |
|
| Where tokens, caches, overrides, and the audit log live. |
|
| Only if you registered a different redirect URL. |
|
| Certificate for automatic code capture (optional). |
Privacy
Your Gazelle data stays on your computer, except for these lookups needed to compute mileage:
Driving distances: OSRM. Only bare latitude/longitude pairs are sent: no names, addresses, or amounts. The default is OSRM's free public demo server; set
GAZELLE_OSRM_URLto use your own.Geocoding: the US Census Bureau geocoder. It is sent your home street address, plus the address of any appointment Gazelle has no coordinates for.
Both results are cached in data/, so each lookup happens once. Of course, whatever Claude reads through the tools is sent to Claude as part of your conversation.
Files in data/ (all gitignored):
File | Contents |
| Your Gazelle OAuth token. Treat it like a password. |
| Your local corrections (amounts, tips). |
| Every change made by this server. |
| Distance and coordinate caches. |
How the numbers are computed (and their limits)
Mileage: for each day, trips run from home to each appointment in start-time order and back home, using real driving distances. Cancelled appointments are skipped. No-shows are included, because you still drove there. Each trip is dated in the appointment's own timezone.
Appointment address: Gazelle usually leaves the appointment's own location empty, so the client's default address is used. If you did a job somewhere else, that trip will be wrong. Check the log.
Deduction estimate: miles × the IRS standard mileage rate for the trip's date. The built-in rates cover 2024 through 2026, including 2026's mid-year change. Rates for later years must be added in
src/mileage/mileage.ts(pull requests welcome). Trips without a known rate are listed undernoRateDates.Value is quoted, not collected: totals come from the service items on each appointment, not from invoices or payments, because not every Gazelle plan includes invoice access through the API. Use
set_appointment_overrideto record what you actually charged, and any tips.Quantities: for service items with quantity ≠ 1, it's unconfirmed whether Gazelle's price is per unit or the line total. Those appointments are flagged
quantityAmbiguous.Gazelle's API is the private API its own apps use. It may change without notice.
Development
npm run dev # run from source (loads .env)
npm test # unit tests (no Gazelle account needed)
npm run typecheck
npm run introspect # dump the live Gazelle schema to docs/schema.json (gitignored)GAZELLE_USE_FIXTURES=1 runs the server against an empty in-memory client. See CLAUDE.md for architecture and conventions, and docs/api-notes.md for what's been verified against the live API.
Contributions are welcome, especially from technicians on Gazelle plans with invoice access. Never include real client data in issues, tests, or pull requests.
License
MIT.
This is an unofficial, independent project. It is not affiliated with, endorsed by, or supported by Gazelle. "Gazelle" is used only to describe what this software connects to.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect Claude or Cursor to books, invoices, bills, payroll, and sealed closes.
Your SMB workspace in Claude or ChatGPT: tasks, notes, sales and Michèle's memory, via OAuth.
Create contacts, move deals, send proposals and invoices, read your inbox, from Claude or ChatGPT.
Connect Claude to Dutch accounting software: e-Boekhouden invoices, contacts and ledgers.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for EZ@Work — manage clients, projects, time entries, and invoices from Claude through natural conversation. OAuth 2.1 with Google sign-in, multi-currency support.5MIT
- AlicenseAqualityFmaintenanceConnects Claude to Jobber to manage clients, jobs, invoices, quotes, and scheduling through natural language.10MIT
- FlicenseBqualityDmaintenanceConnects Claude to your JobNimbus account via API, enabling management of contacts, jobs, notes, and other CRM entities through natural language.19-
- FlicenseNot gradedqualityDmaintenanceConnects Claude to the Qoyod accounting system via its REST API, enabling natural language management of customers, invoices, vendors, journal entries, and other accounting resources through MCP tools.-