dashy-mcp
MCP server exposing Dashy's REST APIas 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 (viaENABLE_API, API_TOKEN, and/or Dashy's existing user auth) is server-sideconfiguration 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 releaseand 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 nestedarray 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 toReleases whenever a v* tag ispushed - 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 andthen deletes a scratch section named mcp-test-<uuid> - never touches your realsections. Dashy also auto-backs up every write to user-data/config-backups/ as asecond safety net.
