Skip to main content
Glama

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: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.

{
  "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-mcp

Do 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

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:

{ "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 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

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.

Available Tools

5 tools
dashy_configA
Destructive

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_itemsA
Destructive

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_keysA
Destructive

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_sectionsA
Destructive

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_systemA
Read-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

    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

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      C
      maintenance
      Provides a structured data interface for Servarr apps (Sonarr, Radarr, Prowlarr) enabling health checks, analytics, simulations, backups, and guarded write operations.
      100
      8 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      13
      131 npm
      MIT