JonDash MCP

An MCP server that lets an AI assistant — Claude Desktop, Claude Code, or any MCP client — read and manage a self-hosted JonDash dashboard.

Ask "is my dashboard up and is there an update?", "what services do I have?", "who signed in this week?" — answered from your own instance, over an authenticated API, with no browser and no screen scraping.

Status: early. One tool works today. get_server_status runs against any JonDash, because it is built on the public health probe. Everything else needs the scoped-token API described in docs/API-CONTRACT.md, which is not in JonDash yet. See Roadmap.

The JonDash project

Repository	What it is
JonDash	The dashboard itself — the app you install and run.
JonDash-addons	The official source of add-on modules and helpers, installed from inside JonDash.
JonDash-mcp (you are here)	An MCP server so an AI assistant can read and manage your instance.

---

How it works

Claude  ──stdio/MCP──>  jondash-mcp  ──HTTPS + Bearer token──>  JonDash  ──>  SQLite

The server holds a scoped API token and talks to JonDash's JSON API. It never touches the database, never scrapes the web UI, and never reuses a browser session — so every request goes through exactly the same permission checks as a signed-in user, and a token can never do more than the account it belongs to.

Requirements

• Node.js 20.11+
• A running JonDash instance you administer
• An API token from that instance (for anything beyond the status check)

Install

git clone https://github.com/jontiadcock/JonDash-mcp.git
cd JonDash-mcp
npm install
npm run build

Configure

All configuration is environment variables:

Variable	Required	Default	Purpose
JONDASH_URL	yes	—	Your instance, e.g. http://localhost:3000
JONDASH_TOKEN	for everything but the status check	—	A token minted in JonDash
JONDASH_TIMEOUT_MS	no	10000	Per-request timeout (1000–60000)
JONDASH_ALLOW_WRITES	no	0	Set to 1 to allow write tools to be registered at all

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "jondash": {
      "command": "node",
      "args": ["C:/path/to/JonDash-mcp/dist/index.js"],
      "env": {
        "JONDASH_URL": "http://localhost:3000",
        "JONDASH_TOKEN": "jd_your_token_here"
      }
    }
  }
}

Claude Code

claude mcp add jondash --env JONDASH_URL=http://localhost:3000 --env JONDASH_TOKEN=jd_your_token_here -- node /path/to/JonDash-mcp/dist/index.js

Minting a token

(Once the API ships — see docs/API-CONTRACT.md.) In JonDash: Account → API tokens → New token, choose the scopes, confirm with your authenticator, and copy the value. It is shown once and never again. Grant read scopes only unless you have a reason not to.

Tools

Tool	Scope needed	What it does
get_server_status	none	Is JonDash up, how long has it been up, what version, is an update available

Planned, once the API exists — read first, writes opt-in:

Tool	Scope
list_services	services:read	your service tiles
list_service_groups	groups:read	shared tile bundles
list_modules	modules:read	installed add-on modules
list_users	users:read	accounts (admin)
query_audit_log	audit:read	filtered audit events (admin)
list_sessions	sessions:read	who is signed in (admin)
add_service / update_service / delete_service	services:write	manage your own tiles
enable_module / disable_module	modules:write	turn modules on and off (admin)
check_for_updates	status:read	trigger an update check

Deliberately not exposed: applying updates, restarting or shutting down the server, exporting or restoring backups, resetting a user's access, deleting users, and anything touching passwords, 2FA secrets or tokens. Those are destructive, lock-you-out, or exfiltration-shaped, and they stay in the web UI behind a real session. A bearer token sitting in an AI client's config is a weaker credential than an interactive password + 2FA login, so this server's reach is deliberately smaller than the UI's — not equal to it.

Security

• Least privilege. The server can only do what its token's scopes allow, intersected with what the owning account is allowed. Write tools additionally require JONDASH_ALLOW_WRITES=1, so the default posture is read-only no matter how broad the token is.
• No back doors. No database access, no HTML scraping, no cookie reuse. If the API cannot do it, this server cannot do it.
• Secrets never surface. The token is redacted from every log line and error message, and the API never returns password hashes, 2FA secrets, backup codes, or session tokens.
• Tool output is data, not instructions. Tile titles, module descriptions and audit entries are written by users; the server tells the model to treat them as content, never as commands.
• Revoke at will. Deleting the token in JonDash cuts this server off immediately.

Report a security problem privately via github.com/jontiadcock rather than opening a public issue.

Development

Command	Description
npm run typecheck	tsc --noEmit
npm run build	compile to dist/
npm run dev	run from source (Node type-stripping)
npm start	run the built server

Debug output goes to stderr — stdout is the JSON-RPC channel and must carry nothing else.

Roadmap

1. Scaffold + get_server_status against the public health probe ✅
2. JonDash ships scoped API tokens + /api/v1 — the spec (blocking, core app)
3. Read tools: services, groups, modules, users, audit, sessions
4. Write tools, opt-in and guarded
5. Module-contributed tools — add-on modules declare their own MCP tools and this server registers them dynamically, so installing a module gives the assistant new abilities with no MCP release

Licence

Personal use only — see LICENSE. Same terms as JonDash: free for your own non-commercial use, no selling, no redistribution.