dashy-mcp

MCP server exposing Dashy's REST API as tools, so an LLM can read and edit your dashboard config: sections, items (tiles), and top-level config keys.

Built with FastMCP.

Enabling the API on your Dashy server

Dashy's API is opt-in and disabled by default. Enabling and securing it (via ENABLE_API, API_TOKEN, and/or Dashy's existing user auth) is server-side configuration specific to how you run Dashy, and out of scope for this project - see Dashy's own docs: Enabling the API.

Install

Download a wheel from the latest release and install it as a uv tool (no repo checkout needed):

uv tool install dashy_mcp-*.whl

This puts a dashy-mcp command on your PATH. Register it with Claude Code:

claude mcp add dashy \
  --env DASHY_URL=https://your-dashy-host \
  --env DASHY_TOKEN=<token> \
  -- dashy-mcp

From source

uv sync
cp .env.example .env   # fill in DASHY_URL and DASHY_TOKEN

claude mcp add dashy \
  --env DASHY_URL=https://your-dashy-host \
  --env DASHY_TOKEN=<token> \
  -- uv run --directory /path/to/dashy-mcp dashy-mcp

Config

Env var	Required	Default
DASHY_URL	yes	-
DASHY_TOKEN	no	none (no auth header sent)
DASHY_CONFIG_FILE	no	conf.yml

Tools

One tool per Dashy API endpoint:

Tool	Endpoint
dashy_list_config_files	GET /api/config
dashy_get_config	GET /api/config/:file
dashy_replace_config	PUT /api/config/:file
dashy_get_key	GET /api/config/:file/:key
dashy_set_key	PUT /api/config/:file/:key
dashy_add_section	POST /api/config/:file/sections
dashy_get_section	GET /api/config/:file/sections/:sid
dashy_update_section	PATCH /api/config/:file/sections/:sid
dashy_delete_section	DELETE /api/config/:file/sections/:sid
dashy_list_items	GET /api/config/:file/sections/:sid/items
dashy_add_item	POST /api/config/:file/sections/:sid/items
dashy_get_item	GET /api/config/:file/sections/:sid/items/:iid
dashy_update_item	PATCH /api/config/:file/sections/:sid/items/:iid
dashy_delete_item	DELETE /api/config/:file/sections/:sid/items/:iid

sid/iid accept either a zero-based index or an exact section name / item title. filename defaults to conf.yml (or DASHY_CONFIG_FILE) on every tool. PATCH-based updates are a shallow merge: only given fields change, and a nested array included in the patch replaces the existing one wholesale.

Development

make help  # list all commands

Command	Does
make sync	uv sync
make test	Offline tests - one per endpoint, mocked HTTP
make test-integration	Tests against the live instance (needs DASHY_URL/DASHY_TOKEN)
make build	Build wheel + sdist into dist/
make bump-patch / bump-minor / bump-major	Bump the version in pyproject.toml + uv.lock
make clean	Remove build artifacts

The release workflow (.github/workflows/release.yml) builds and publishes to Releases whenever a v* tag is pushed - so the usual flow is make bump-patch, commit, then tag and push.

The integration suite reads real config and, for the write lifecycle test, creates and then deletes a scratch section named mcp-test-<uuid> - never touches your real sections. Dashy also auto-backs up every write to user-data/config-backups/ as a second safety net.