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

Tools

4 resource-scoped tools, each covering multiple Dashy API endpoints (14 total) via an operation parameter. Call a tool with operation set to one of its listed operations and an arguments dict matching that operation's parameters — the tool's own description (visible to your MCP client) lists every operation, its signature, and a one-line doc.

Example: dashy_section(operation="dashy_get_section", arguments={"sid": "Media"}). Endpoint-level naming is preserved as the operation value:

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

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.