Gorelo MCP server

Lets an AI assistant read your Gorelo PSA — your ticket backlog, clients, contacts and managed devices — by talking to the Gorelo API on your behalf.

It runs on your own machine and speaks MCP over stdin/stdout. Nothing is hosted, nothing is exposed to the internet, and your API key never leaves your computer.

Twenty-three tools, nineteen of them read-only. Plain Ruby — no gems, no Bundler, no build step.

⚠️ Correction — 11 September 2026

Earlier versions of this README stated, as established fact, that Gorelo has no readable time-entry API and that per-user hours were impossible. That was true when it was written. It is false now. Gorelo’s 4 September 2026 release shipped GET /v1/time-entries — one row per logged entry, tenant-wide, each carrying the user who logged it — along with /v1/contracts, /v1/billing-roles and /v1/work-types.

gorelo_time_report has been rebuilt on it. It no longer attributes a ticket’s hours to the lead assignee, no longer warns that per-person totals are “indicative”, and no longer costs one request per ticket. If you built anything on the old limitation, or repeated it to anyone, it needs revisiting. Details: what changed on 4 September 2026.

One more thing from that release: until 3 October 2026 a contract was what Gorelo’s web UI called a “Contract Group”, and a ServiceLine was what the UI called a “Contract”. That was true then; the UI now uses the API’s words. See contract naming.

---

Install

Pick whichever you already have. Both are equally supported.

# Ruby (skip if `ruby -v` already works)
sudo apt update && sudo apt install -y ruby      # Debian/Ubuntu
# brew install ruby                              # macOS

git clone  ~/gorelo-mcp     # or just copy the folder there
cd ~/gorelo-mcp
cp .env.example .env && nano .env      # fill in your API key

Check it starts and answers:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
  | ruby gorelo-mcp-server.rb

You want a JSON line containing "serverInfo", plus two [gorelo-mcp] lines on stderr.

Then add it to your MCP client’s config. For Claude Desktop that is %APPDATA%\Claude\claude_desktop_config.json on Windows, or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS:

{
  "mcpServers": {
    "gorelo": {
      "command": "wsl.exe",
      "args": ["-d", "Ubuntu", "-e", "/usr/bin/ruby",
               "/home/YOURNAME/gorelo-mcp/gorelo-mcp-server.rb"]
    }
  }
}

On Linux or macOS, drop the wsl.exe wrapper:

{
  "mcpServers": {
    "gorelo": {
      "command": "/usr/bin/ruby",