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?" — and get answers 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.

How it works

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

The MCP 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 is subject to 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:

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

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

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.

If you find a security problem, please report it privately via github.com/jontiadcock rather than opening a public issue.

Development

npm run typecheck   # tsc --noEmit
npm run build       # -> dist/
npm run dev         # run from source (Node type-stripping)

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.