Skip to main content
Glama
README.md
# dashy-mcp

MCP connector for a self-hosted [Dashy](https://github.com/Lissy93/dashy) 4.9.19 dashboard. It speaks the opt-in REST API plus three read-only server endpoints over stdio and over stateless Streamable HTTP on localhost.

Dashy is MIT software. This connector is MIT. It does not copy Dashy source. It is not affiliated with Lissy93/dashy.

`spec/api-inventory.json` is a hand-written inventory of Dashy 4.9.19 `docs/api.md`, the 14 routes in `services/endpoints/api/index.js`, and the named endpoints mounted in `services/app.js`. It records the release, commit `5a8dc18c1bceeeac9d5c0832af0517c709e163a4`, MIT, file sha256s, and `routeTreeSha256`. `scripts/gen-operations.mjs` maps that inventory onto tool actions or exclusions and writes `src/operations.ts` and `dashy.routes.json`. A route that is neither mapped nor excluded fails generation. Do not edit `src/operations.ts` by hand. `npm run ci` reads only the committed inventory.

`DASHY_URL` and `DASHY_TOKEN` (or `DASHY_TOKEN_FILE`) are required. There is no default origin. Each request sends `Authorization: Bearer`. The token is never placed in the URL.

## Setup

```bash
npm install
npm run ci
npm start
npm run start:http
```

`npm start` speaks stdio. `npm run start:http` serves Streamable HTTP at `http://127.0.0.1:3000/mcp` and `GET /health`. HTTP mode has no authentication of its own. Keep it on localhost.

The Dashy process must set `ENABLE_API=true` and `API_TOKEN` to the same secret. The API is off unless `ENABLE_API` is the string `true`. A wrong or missing bearer token is HTTP 401 when `API_TOKEN` is set.

```json
{
  "mcpServers": {
    "dashy": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "DASHY_URL": "http://127.0.0.1:18741",
        "DASHY_TOKEN": "...",
        "DASHY_ALLOW_WRITES": "false"
      }
    }
  }
}
```

Prefer `DASHY_TOKEN_FILE` (mode 0600) over `DASHY_TOKEN`. The connector never prints the token.

```bash
docker build -t dashy-mcp .
docker run -p 127.0.0.1:3000:3000 \
  -e DASHY_URL=http://127.0.0.1:18741 \
  -e DASHY_TOKEN=... \
  dashy-mcp
```

Do not put secrets in the image.

Regenerate the registry from the committed inventory.

```bash
npm run gen:operations
node scripts/gen-operations.mjs --check
node scripts/gen-operations.mjs --source-root /path/to/dashy --check
```

`--source-root` checks the pinned file sha256s. It does not rewrite the inventory.

`scripts/live-check.mjs` talks to a real server over stdio. Set `DASHY_URL`. Set `DASHY_TOKEN` or `DASHY_TOKEN_FILE`. The script unsets `DATABASE_URL`. It prints pass or fail lines only, and it redacts the token and the throwaway config hash. It does not run inside `npm run ci`. A missing token is a failure.

Isolated local runtime scripts live under `/workspace/tools/dashy` (`start.sh`, `stop.sh`). They keep the throwaway `conf.yml` and token under `/workspace/tools/dashy/runtime` (mode 0700/0600). No Docker.

## Config

| Variable | Meaning |
| --- | --- |
| `DASHY_URL` | Required. Origin only, `http` or `https`, no userinfo, query, hash, or path. Example `http://127.0.0.1:18741`. Do not append `/api`. |
| `DASHY_TOKEN` | Required unless `DASHY_TOKEN_FILE` is set. Sent as `Authorization: Bearer`. Redacted in logs, errors, previews, and results. Minimum 8 characters. |
| `DASHY_TOKEN_FILE` | Optional. chmod 600 file whose trimmed contents are the token. Used when `DASHY_TOKEN` is omitted. |
| `DASHY_ALLOW_WRITES` | Must be the literal `true` before a confirmed write is sent. |
| `DASHY_PER_MINUTE` | Local request budget. Default 30. Cache hits do not spend it. Live-check sets 600. |
| `DASHY_TIMEOUT_MS` | Upstream timeout. Default 20000. |
| `DASHY_CACHE_TTL_SEC` | Read cache TTL. Default 60. Writes clear the cache. |
| `DASHY_CONTACT` | Contact token in the User-Agent. Must not contain the API token. |
| `MCP_TRANSPORT` | `stdio` or `http`. `--http` overrides. |
| `PORT` | HTTP port. Default 3000. |

Invalid values are reported by field name and issue code. The rejected value is not included.

Calls go to paths from the operations registry. `Accept` is `application/json`. JSON writes send `Content-Type: application/json`. Redirects are refused. There are no automatic retries, including HTTP 429.

## Tools

Five action-field tools. `action` selects the operation. Unknown fields and fields that do not belong to that action are rejected before any HTTP call. The string `"true"` is not a boolean and is rejected.

| Tool | Actions | HTTP |
| --- | --- | --- |
| `dashy_system` | `health`, `info`, `schema` | `GET /healthz`, `GET /system-info`, `GET /schema.json` |
| `dashy_config` | `list`, `get`, `replace` | `GET /api/config`, `GET /api/config/{filename}`, `PUT /api/config/{filename}` |
| `dashy_keys` | `get`, `replace` | `GET` or `PUT /api/config/{filename}/{key}` |
| `dashy_sections` | `add`, `get`, `update`, `delete` | `POST`, `GET`, `PATCH`, `DELETE` on `/api/config/{filename}/sections/...` |
| `dashy_items` | `list`, `add`, `get`, `update`, `delete` | item routes under a section |

`filename` is a basename ending in `.yml` or `.yaml`, for example `conf.yml`. `sid` is a zero-based index or an exact section name. `iid` is a zero-based index or an exact item title. `key` is `pageInfo`, `appConfig`, `sections`, or `pages`.

`list` on files and items accepts `offset` and `limit`. Dashy has no page query. The connector fetches the full list and slices it. Omitted `limit` returns the whole list. `limit` is 1 to 500.

Section `add` needs `document.name`. Item `add` needs `document.title`. `replace` on a key sends `replacement` as the entire new value (object or array). It does not merge. `PATCH` is a shallow merge, matching Dashy: nested arrays you include are replaced wholesale.

Dashy 4.9.19 has no rebuild endpoint. `dashy_system` does not invent one.

### Examples

List files, then read the main config:

```json
{ "action": "list", "offset": 0, "limit": 20 }
```

```json
{ "action": "get", "filename": "conf.yml" }
```

Dry-run a new tile (nothing is sent):

```json
{
  "action": "add",
  "filename": "conf.yml",
  "sid": "0",
  "document": { "title": "Grafana", "url": "https://grafana.local", "icon": "hl-grafana" }
}
```

Send it:

```json
{
  "action": "add",
  "filename": "conf.yml",
  "sid": "0",
  "document": { "title": "Grafana", "url": "https://grafana.local", "icon": "hl-grafana" },
  "confirm": true
}
```

`confirm: true` still does not send unless `DASHY_ALLOW_WRITES=true`.

## Safety

Reads run without a write flag. A write is sent only when `confirm` is the boolean `true` and `DASHY_ALLOW_WRITES=true`. That gate covers all eight mutations: config replace, key replace, section add/update/delete, and item add/update/delete.

Omit `confirm`, or pass boolean `false`, and the tool returns a dry-run preview of method, path, and body. It sends nothing. `blocked` is false on that preview. `confirm: true` with writes disabled returns the same preview with `blocked` true and the reason `DASHY_ALLOW_WRITES is not true. The write was not sent.`

Omitted fields are dropped. `statusCheck: false`, `id: 0`, and empty strings are sent when you set them.

The API token is redacted in logs, errors, previews, and tool results, including percent-encoded and JSON-escaped forms. URL userinfo is stripped. Inside config JSON, values under sensitive keys are replaced with `[redacted]`. That includes `password`, `hash`, `token`, `secret`, `clientSecret`, and the whole `keycloak` object (realm client settings). `hashRouting` is kept. Usernames are kept. A short credential (under 8 characters) forces a generic upstream message instead of a partial mask.

`GET /status-check` and `GET /ping-check` are excluded. They make the server contact a caller-supplied host. `GET /cors-proxy` is excluded for the same reason. `POST /config-manager/save` is the legacy YAML writer and is excluded in favor of `PUT /api/config/{filename}`. `GET /get-user` can echo a proxy identity header and is excluded. `GET /opensearch.xml` is browser XML, not a JSON config call.

These are not inventory routes: `status-ping` is named in source and not mounted; `serve-config` serves YAML files for the UI; alias redirects and the SPA fallback are not JSON operations.

Dashy rewrites YAML on save, drops comments and anchors, and keeps a timestamped backup under `user-data/config-backups/` unless `DISABLE_CONFIG_BACKUPS=true`. `conf.yml` writes are schema-checked. Other YAML files are not. Files are capped at 256 KB. Concurrent writes are last-write-wins.

## Provenance and coverage

| | |
| --- | --- |
| Upstream | Lissy93/dashy 4.9.19, commit `5a8dc18c1bceeeac9d5c0832af0517c709e163a4` |
| License (upstream) | MIT |
| License (this connector) | MIT |
| Inventory routes | 23 |
| Mapped | 17 (14 REST + `GET /healthz`, `GET /system-info`, `GET /schema.json`) |
| Excluded | 6 (status-check, ping-check, cors-proxy, config-manager/save, get-user, opensearch.xml) |
| Tools | 5 |
| Write actions | 8, all confirm-gated |

Path templates in the registry use `{param}`. The Express source uses `:param`. The generator keys off the inventory templates.

## Rivals

Checked 17 Nov 2026. GitHub search for Dashy MCP servers returned one project. npm search did not return a Dashy MCP package. SavageCore/dashy-mcp publishes a Python wheel, not an npm package.

| | SavageCore/dashy-mcp | this connector |
| --- | --- | --- |
| Surface | 4 tools, 14 REST operations via an `operation` argument | 5 tools, 14 REST operations plus health, system-info, and schema |
| Writes | Sent when the operation is a mutation. The README describes integration tests that create and delete a scratch section, and Dashy's own YAML backups. It does not describe a confirm flag or an allow-writes gate. | Dry-run unless `confirm` is boolean `true` and `DASHY_ALLOW_WRITES=true` |
| Auth | `DASHY_TOKEN` optional. No header when unset. | Token required. Bearer on every request. Redacted in outputs. |
| Exclusions | Not described. The 14 REST routes are the whole surface. | SSRF-prone probes and the legacy YAML writer are excluded on purpose. |
| Schema | Operation name plus an `arguments` object. | Strict Zod object per tool. Unknown fields rejected. |

## Tests

`npm run ci` typechecks, lints, runs Vitest, builds, and checks that `src/operations.ts` matches the inventory.

Vitest covers the write-guard matrix for every mutation (omit, false, true, writes off, writes on, `TRUE`, `1`), preview versus confirmed, unknown fields, spec coverage, HTTP 401, 403, 404, 422, and 429 mapping, and leak regressions for the API token and for `hash` / `keycloak` fields inside config JSON. 403, 422, and 429 are simulated. See `LIVE-CHECK.md` for which codes a real Dashy process returned.

## Live check

```bash
unset DATABASE_URL
/workspace/tools/dashy/start.sh
cd /workspace/connectors/dashy
export DASHY_URL=http://127.0.0.1:18741
export DASHY_TOKEN_FILE=/workspace/tools/dashy/runtime/api.token
unset DASHY_TOKEN
npm run live-check
/workspace/tools/dashy/stop.sh
```

`start.sh` is idempotent. It binds `127.0.0.1` only, writes a throwaway `conf.yml`, and does not use Docker. `stop.sh` closes the port.

TDQS

A4/5.0

Scored across 5 tools

Disambiguation4/5

The tools are partitioned by resource level (system, whole config file, top-level key, section, item), which is mostly clear. There is some inevitable overlap — dashy_config replace vs dashy_keys replace vs dashy_sections update can all mutate the same document, and dashy_keys get(key=sections) duplicates dashy_sections get — but the descriptions explicitly delineate scope.

Naming Consistency5/5

Every tool follows the same dashy_<resource> snake_case noun pattern, and the resource hierarchy (system → config → keys → sections → items) is coherent. Actions are consistently multiplexed via an action parameter rather than encoded in names, so the convention is applied uniformly.

Tool Count5/5

Five tools is well-scoped for a dashboard config server, and each one covers a distinct layer of the document rather than being a thin wrapper. The action-multiplexing keeps the surface small (~16 operations) while staying navigable.

Completeness4/5

Full lifecycle coverage exists for the hierarchical parts of the config (sections and items have add/update/delete), plus file-level and key-level read/write. Minor gaps: no way to create or delete a config file, and dashy_keys cannot add or remove top-level keys — though those keys are a fixed set, so agents can work around it.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues