dashy-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@dashy-mcp check the Dashy dashboard health and show its system info"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
dashy-mcp
MCP connector for a self-hosted 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
npm install
npm run ci
npm start
npm run start:httpnpm 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.
{
"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.
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-mcpDo not put secrets in the image.
Regenerate the registry from the committed inventory.
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.
Related MCP server: unraid-mcp
Config
Variable | Meaning |
| Required. Origin only, |
| Required unless |
| Optional. chmod 600 file whose trimmed contents are the token. Used when |
| Must be the literal |
| Local request budget. Default 30. Cache hits do not spend it. Live-check sets 600. |
| Upstream timeout. Default 20000. |
| Read cache TTL. Default 60. Writes clear the cache. |
| Contact token in the User-Agent. Must not contain the API token. |
|
|
| 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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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:
{ "action": "list", "offset": 0, "limit": 20 }{ "action": "get", "filename": "conf.yml" }Dry-run a new tile (nothing is sent):
{
"action": "add",
"filename": "conf.yml",
"sid": "0",
"document": { "title": "Grafana", "url": "https://grafana.local", "icon": "hl-grafana" }
}Send it:
{
"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 |
License (upstream) | MIT |
License (this connector) | MIT |
Inventory routes | 23 |
Mapped | 17 (14 REST + |
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 | 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 |
Auth |
| 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 | 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
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.shstart.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.
Available Tools
5 toolsdashy_configADestructive
List config files, get one file as JSON, or replace a whole file. Replace runs only when confirm is true and DASHY_ALLOW_WRITES=true. Otherwise it is a dry-run and no HTTP write is sent. List accepts offset and limit applied after the fetch. Actions: list, get, replace.
Inputs: action (required), limit, offset, confirm, +2 more.
dashy_itemsADestructive
List, add, get, shallow-merge, or delete a tile in a section. sid and iid are an index or an exact name or title. Add needs document.title. List accepts offset and limit applied after the fetch. Writes run only when confirm is true and DASHY_ALLOW_WRITES=true. Actions: list, add, get, update, delete.
Inputs: action (required), iid, sid, limit, +4 more.
dashy_keysADestructive
Get or replace one top-level key: pageInfo, appConfig, sections, or pages. Replace overwrites that key. It does not merge. Writes run only when confirm is true and DASHY_ALLOW_WRITES=true. Actions: get, replace. Listing sections is get with key sections.
Inputs: action (required), key, confirm, filename, +1 more.
dashy_sectionsADestructive
Add, get, shallow-merge, or delete a dashboard section. sid is a zero-based index or an exact section name. Add needs document.name. Writes run only when confirm is true and DASHY_ALLOW_WRITES=true. Actions: add, get, update, delete.
Inputs: action (required), sid, confirm, document, +1 more.
dashy_systemARead-only
Dashy process health, host resource snapshot, and the config JSON Schema. Reads only. Actions: health (GET /healthz), info (GET /system-info), schema (GET /schema.json). Dashy has no rebuild endpoint in 4.9.19.
Inputs: action (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Query and manage SquaredUp dashboards, data streams, the knowledge graph, and KPIs (US region).
Read NodePing checks, uptime, results and events; mute checks, manage maintenance and schedules.
Query and manage SquaredUp dashboards, data streams, the knowledge graph, and KPIs (EU region).
Read devices, users, keys, ACLs and DNS for a tailnet; manage devices, routes and auth keys.
Related MCP Servers
- AlicenseCqualityCmaintenanceProvides a structured data interface for Servarr apps (Sonarr, Radarr, Prowlarr) enabling health checks, analytics, simulations, backups, and guarded write operations.1008 npmMIT
- AlicenseBqualityCmaintenanceEnables querying and managing an Unraid server through its official GraphQL API, exposing system, array, Docker, VM, share, notification, metrics, logs, and health actions via a single MCP tool. Write operations are gated by two independent locks and confirmation, with read-only behavior by default.1MIT
- AlicenseAqualityCmaintenanceEnables managing a self-hosted media library through its HTTP API, with scoped toolsets, confirm-gated writes, dry-run previews, and read caching. Supports libraries, items, collections, playlists, podcasts, sessions, stats, tags, genres, and administrative operations.13131 npmMIT
- AlicenseAqualityCmaintenanceEnables managing a self-hosted Headscale control server through its HTTP API, covering users, nodes, pre-auth and API keys, auth, policy, and metadata with write previews and confirmations.4MIT