Ask GorillaDesk (gorilladesk-mcp)
# Ask GorillaDesk (gorilladesk-mcp)
Read-only MCP server so Claude, ChatGPT, or Cursor can answer pest-business questions from your [GorillaDesk](https://gorilladesk.com/) account in plain English.
It looks things up. It does **not** create customers, change jobs, or take payments.
## Example questions
- How many customers do I have?
- Who owes me money?
- What’s on the schedule this week?
- Who are my technicians?
- How’s money this month?
- Give me a Monday morning briefing
## Auth
GorillaDesk uses a company API key (Bearer token).
1. Open [Addons → API](https://beta.gorilladesk.com/addons/api)
2. Generate / copy the key
3. Put it in `.env` as `GORILLADESK_API_KEY` (local) or paste it at `/connect` (hosted)
Docs: https://api.gorilladesk.com/docs/
## Local install
```bash
cd gorilladesk-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
# edit .env and paste GORILLADESK_API_KEY
```
Wire Cursor / Claude Desktop to `scripts/run_mcp.sh` (see `mcp.json.example`).
## Hosted HTTP
```bash
export GORILLADESK_MCP_HOSTED=1
export GORILLADESK_VAULT_SECRET='a-long-random-string'
./scripts/run_mcp_http.sh
```
| Path | Role |
|------|------|
| `/` | Landing |
| `/gorilladesk` | Product page |
| `/connect` | Paste API key → mint bearer token |
| `/mcp` | Streamable HTTP MCP |
| `/healthz` | Health |
## Safety
- Client allows **GET only**
- Tools annotated `readOnlyHint=True`
- Owner tools return an `answer` string agents should read aloud
## Relay
Product page lives under Relay at `/gorilladesk`. Marketing host: the `relay-mcp` Vercel project (fieldwork-mcp `landing/`).
## Builder notes
```bash
pytest
ruff check src tests
```
TDQS
Scored across 19 tools
There is overlap between natural-language query tools (e.g., how_much_money, who_owes_me_money) and generic search tools (e.g., search_invoices, search_customers), though descriptions mitigate confusion with 'Prefer' hints. A few pairs like search_customers/find_customer and search_jobs/whats_on_the_schedule are nearly interchangeable and could lead to misselection.
The set mixes natural-language question phrases (how_much_money, who_are_my_technicians) with standard verb_noun patterns (search_customers, get_job). Each style is internally consistent, but the lack of a unified naming convention makes it harder to predict tool names across the whole server.
19 tools is slightly over the ideal 3-15 range but appropriate for the breadth of the GorillaDesk domain (customers, jobs, invoices, payments, estimates, services, users). The two-layer design (answer-oriented vs. data-access) adds functionality but also inflates the count.
The toolkit covers the core entities needed for a read-only business assistant. Minor gaps exist, such as missing get_* tools for payments, estimates, services, and users, but the search tools likely return sufficient detail for most 'ask' scenarios.