{ "markdown": "\n

\n \n \n \"dashboardbase\"\n \n

\n\n

dashboardbase MCP

\n\n

\n Stop guessing whether your dashboard JSON is right. Ask.\n

\n\n

\n \"npm\n \"MCP\n \"MIT\n \"Dashboardbase\"\n

\n\nThis is the official [MCP server](https://modelcontextprotocol.io) for [dashboardbase](https://dashboardbase.com). Add it to your AI tool and it can check a widget endpoint's response — or a whole dashboard setup file — against the contract dashboardbase actually enforces, before you ever open the app.\n\n> The [dashboardbase skill](https://github.com/dashboardbase/skills) teaches your agent the JSON contract. This MCP lets it **check its own work**. Use both: the skill gets the shape right, the MCP proves it.\n\n---\n\n## What this MCP does\n\nIt gives your agent two tools:\n\n| Tool | What it checks |\n| --- | --- |\n| `validate_setup_file` | A dashboardbase setup file — the JSON that provisions a whole dashboard's widgets and datasources. Reports errors and warnings with the field, line and column. |\n| `validate_widget_response` | The JSON body a widget endpoint returns, against the widget contract. Reports the path and message for each problem. |\n\nBoth call the public dashboardbase validation API. **No account, no API key, nothing to configure.**\n\n## Before / after\n\n**Without it** — your agent writes an endpoint, you deploy it, you wire it into dashboardbase, the widget shows an error, you go read the docs, you fix it, you deploy again.\n\n**With it** — your agent writes the endpoint, validates the response, fixes the two things that were wrong, and hands you something that renders the first time.\n\n```\nInvalid setup file — 2 errors, 1 warning\n\n mappings[0].type 14:9 Unknown widget type \"guage\"\n mappings[1].path 22:5 Path must start with \"/\"\n\n warning mappings[2] No refreshInterval set\n```\n\n---\n\n## Install\n\n### Claude Code\n\n```bash\nclaude mcp add dashboardbase -- npx -y @dashboardbase/mcp\n```\n\n### One click\n\n\"Install\n\"Install\n\n### Claude Desktop\n\nDownload `dashboardbase-mcp.mcpb` from the [latest release](https://github.com/dashboardbase/mcp/releases/latest) and drag it into Claude Desktop's extensions settings. The bundle is self-contained — you don't even need Node.\n\n### Cursor, Windsurf, and most other clients\n\nThese use the `mcpServers` shape. Add it to `~/.cursor/mcp.json` (Cursor), `~/.codeium/windsurf/mcp_config.json` (Windsurf), or your client's equivalent:\n\n```json\n{\n \"mcpServers\": {\n \"dashboardbase\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@dashboardbase/mcp\"]\n }\n }\n}\n```\n\n### VS Code\n\nVS Code is the exception — it uses `servers` rather than `mcpServers`, and requires an explicit `type`. In `.vscode/mcp.json` (workspace) or your user profile:\n\n```json\n{\n \"servers\": {\n \"dashboardbase\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@dashboardbase/mcp\"]\n }\n }\n}\n```\n\n### Codex CLI\n\nCodex uses TOML. Easiest is the CLI:\n\n```bash\ncodex mcp add dashboardbase -- npx -y @dashboardbase/mcp\n```\n\nOr by hand in `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.dashboardbase]\ncommand = \"npx\"\nargs = [\"-y\", \"@dashboardbase/mcp\"]\n```\n\nRequires **Node.js 20 or newer** — that's the only prerequisite, and only for the `npx` routes. Nothing else to configure: the validation API is public, so there's no account, key or environment variable to set.\n\n### Staying up to date\n\nTwo different things arrive by two different routes, which is worth knowing:\n\n**Better error messages arrive on their own.** The server holds no schemas — it calls the live API — so as validation messages improve, you see them immediately. Nothing to update.\n\n**New tools need a package update.** If a release adds a tool, you get it once the package updates *and* your client restarts the server. A running server's tool list is fixed for the session.\n\n| How you installed | How you update |\n| --- | --- |\n| `npx` (Claude Code, Cursor, VS Code, Windsurf, Codex) | Automatic — restart your client and the next server start picks up the newest version. |\n| Claude Desktop `.mcpb` | Pinned at install. Download the new bundle from [releases](https://github.com/dashboardbase/mcp/releases/latest) and drag it in again. |\n| Docker | `docker pull` / rebuild the image. |\n\nCheck what you're running:\n\n```bash\nnpx -y @dashboardbase/mcp --version\n```\n\nIf that reports an older version than [the latest release](https://github.com/dashboardbase/mcp/releases/latest), npm is serving cached registry metadata — a just-published version can take a few minutes to show up. Force it:\n\n```bash\nnpx -y @dashboardbase/mcp@latest --version\n```\n\nReleases follow [semver](https://semver.org): new tools are a minor bump and never break existing calls, so updating is safe by default.\n\n---\n\n## Using it\n\n### First, check it's connected\n\n```bash\nclaude mcp list\n```\n\nYou should see `dashboardbase` listed as connected. Inside a Claude Code session, `/mcp` shows the server and its two tools. In other clients, look for `dashboardbase` in the MCP or tools panel.\n\nIf it isn't there, the server never started — check that `node --version` is 20 or newer, and that your config file has valid JSON.\n\n### Then just ask\n\n**You don't call these tools yourself.** Describe what you want and the agent decides to call them, the same way it decides to read a file. There's no special syntax and nothing to remember.\n\nValidating something you already have:\n\n- _\"Validate my dashboardbase setup file\"_\n- _\"Is `.dashboardbase/revenue.json` valid?\"_\n- _\"Check this against the dashboardbase contract\"_ — then paste the JSON\n\nValidating as part of building:\n\n- _\"Build a KPI endpoint for MRR, then validate the response it returns\"_\n- _\"Add a gauge widget to my setup file and make sure it still validates\"_\n\nDebugging something broken:\n\n- _\"My gauge widget shows an error in dashboardbase — check what my endpoint returns against the contract\"_\n- _\"Why is dashboardbase rejecting my setup file?\"_\n\n### What it looks like\n\n> **You:** My revenue widget isn't rendering. Check `.dashboardbase/revenue.json`.\n>\n> **Agent:** *calls `validate_setup_file`*\n>\n> ```\n> Invalid setup file — 2 errors\n>\n> mappings[0].type 14:9 Unknown widget type \"guage\"\n> mappings[1].path 22:5 Path must start with \"/\"\n> ```\n>\n> **Agent:** Two problems — `guage` is a typo for `gauge`, and the second mapping's\n> path is missing its leading slash. Fixing both now.\n>\n> *edits the file, calls `validate_setup_file` again*\n>\n> ```\n> Valid setup file — no errors.\n> ```\n\nThat loop — validate, fix, re-validate — is the whole point. The agent closes it without you opening dashboardbase.\n\n### Or invoke it directly\n\nIn Claude Code, the server adds a slash command — type `/` and it's in the menu:\n\n```\n/mcp__dashboardbase__validate .dashboardbase/revenue.json\n```\n\nLeave the path off and it validates whatever you're working on, or whatever you paste next. This is the deterministic route: it doesn't depend on the agent deciding the tool is relevant.\n\n> The middle segment comes from the name you installed under. If you ran `claude mcp add dashboardbase …` it's `/mcp__dashboardbase__validate`; install it as something else and that segment changes to match.\n\nIn clients that don't support MCP prompts, just name the tool in plain language:\n\n- _\"Use validate_setup_file on .dashboardbase/revenue.json\"_\n- _\"Use validate_widget_response to check this\"_\n\nAgents sometimes need the nudge the first time; after that they usually pick it up on their own.\n\n### The two tools\n\n| Tool | Arguments | Notes |\n| --- | --- | --- |\n| `validate_setup_file` | `content` — the file text
`path` — read from disk instead | Give one or the other. |\n| `validate_widget_response` | `response` — the endpoint's JSON body
`path` — read from disk instead
`widgetType` — optional, e.g. `kpi` | Inferred from the response when `widgetType` is omitted. |\n\nTwo things worth knowing:\n\n- **`path` only exists over stdio.** A hosted HTTP deployment has no access to your disk, so the parameter isn't offered there — pass `content` / `response` instead.\n- **`validate_widget_response` wants the full response body** — the `title` / `actions` / `data` / `alert` envelope your endpoint actually returns, not just the inner `data` payload.\n\n### Configuration\n\nEverything is optional.\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `DASHBOARDBASE_API_URL` | `https://api.dashboardbase.com` | Point at a different environment. |\n| `DASHBOARDBASE_API_KEY` | _unset_ | Sent as `x-api-key`. Not needed for the public API. |\n| `DASHBOARDBASE_TIMEOUT_MS` | `15000` | Request timeout in milliseconds. |\n\n### Running it as an HTTP server\n\nFor containers or a shared internal deployment:\n\n```bash\nnpx @dashboardbase/mcp --http --port 3000\n# or\ndocker build -t dashboardbase-mcp . && docker run -p 3000:3000 dashboardbase-mcp\n```\n\nServes Streamable HTTP at `/mcp` and a health check at `/health`. It's fully stateless, so it scales horizontally with no session affinity. Browser origins are refused unless you allowlist them with `--allowed-origin https://example.com`. The file-reading `path` parameter is **not** exposed in this mode.\n\n---\n\n## What's in the repo\n\n```\nmcp/\n├── src/\n│ ├── index.ts # CLI entry — stdio by default, --http optional\n│ ├── server.ts # Registers the two tools\n│ ├── api.ts # Client for the dashboardbase Tools API\n│ ├── format.ts # Renders results as readable text\n│ ├── http.ts # Stateless Streamable HTTP handler\n│ └── tools/ # One file per tool\n├── test/ # Unit tests, no network required\n├── tools.json # OpenAPI spec for the validation API\n├── server.json # MCP Registry manifest\n├── manifest.json # Claude Desktop bundle manifest\n└── Dockerfile\n```\n\n## How validation works\n\nThe server doesn't carry a copy of the schemas — it calls the live dashboardbase validation API. So it **can't drift from what the platform accepts**, and error messages get better as the API does, with nothing to upgrade on your side.\n\nThat applies to the validation rules and messages, not to the server itself — a release that adds a tool still needs a package update. See [Staying up to date](#staying-up-to-date).\n\n## Related\n\n- **[dashboardbase](https://dashboardbase.com)** — the product. Build, host, and share dashboards from your APIs.\n- **[dashboardbase skill](https://github.com/dashboardbase/skills)** — teaches your agent the JSON contract so it writes correct endpoints in the first place. Pairs directly with this MCP.\n- **[Documentation](https://app.dashboardbase.com/documentation)** — widget reference, JSON contract, webhook setup.\n\n## Contributing\n\nFound a gap or a confusing error? Open an issue. Note that the validation rules themselves live in the dashboardbase backend — if a *message* is unclear that's still worth reporting here, and we'll fix it upstream.\n\n## License\n\nMIT — see [LICENSE](LICENSE). Fork it, adapt it, ship it.\n\nThe MIT license covers the code in this repo. \"dashboardbase\" is a trademark of dashboardbase — see [dashboardbase.com](https://dashboardbase.com). You're free to use and adapt the server; please don't use the name or branding in a way that implies official affiliation.\n", "bytes": 12580, "sha": "7d49bba93dcd0d249810ca87dd7bbd822beefdb7a278c74f2ac3d4e0db2fe98b", "repo_slug": "dashboardbase/mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_com_dashboardbase_mcp_68631d64/readme" }