English · 简体中文

DrPanda MCP

A read-only MCP service for production troubleshooting.

Register MySQL, MongoDB, Elasticsearch, Redis, GitLab, RabbitMQ, Kafka and CLS connections (addresses, credentials and allowed scope) in a web console. MCP clients such as Cursor, Codex and DeepSeek Harness call /mcp over Streamable HTTP; models can only use read-only tools by target name.

The model never supplies hosts, accounts, or passwords itself.

Why DrPanda MCP

Production troubleshooting often requires looking at logs, code, databases, caches and message queues at the same time. Giving production credentials directly to a model is risky; read-only proxies, ad-hoc screenshots and manual lookups are hard to reproduce and audit.

DrPanda MCP narrows "what can be queried" into three boundaries:

1. Connection boundary: only targets registered in the web console are reachable;
2. Operation boundary: only a read-only whitelist is executed; admin commands and high-cost queries are rejected before connecting;
3. Identity boundary: web login and MCP bearer tokens are independent, and every call is audited under the real administrator.

Status

M0–M7 are implemented and tested:

• Tools: 28
• Quality gate: GitHub Actions (pytest / ruff / docs link check); see the CI badge above
• Default listen: 127.0.0.1:8111
• Default languages: English (UI, MCP, CLI, docs); Chinese docs live under docs/zh-CN/
• First-run setup supports SQLite / MySQL / PostgreSQL config stores
• Server-rendered web console; interactive features require JavaScript, while authentication and validation stay server-side

Real integration coverage:

• MySQL / MongoDB / Elasticsearch / Redis / RabbitMQ verified against real Docker upstreams;
• MySQL TLS/mTLS, target-level CA, ES multi-host failover and multiple Mongo auth modes are covered;
• Kafka, CLS and GitLab tools are implemented and unit-tested, but not yet end-to-end verified against real upstreams.

Quick start

Requirements

• Python >= 3.11
• uv
• SQLite is used by default; no extra database is required for the first run

From source (recommended for development):

git clone https://github.com/linyu19872008/dr-panda-mcp.git
cd dr-panda-mcp
uv sync
cp .env.example .env   # optional; defaults are used otherwise
uv run dr-panda-mcp    # automatically loads ./.env from the current directory

Or install as a command-line tool from PyPI:

uv tool install dr-panda-mcp
# Optional config-store drivers:
# uv tool install 'dr-panda-mcp[mysql]'
# uv tool install 'dr-panda-mcp[postgres]'
dr-panda-mcp

A PyPI install uses data/ in the current working directory; start it from a dedicated directory.

Open:

http://127.0.0.1:8111/

On the first run, the setup wizard asks you to:

1. set an administrator password (at least 8 characters);
2. choose a config store: SQLite (recommended locally) / MySQL / PostgreSQL;
3. test the connection (the finish button unlocks only after a successful test);
4. finish setup and save the MCP token shown on the completion page.

When registering a target, a new target must pass a connection test before it can be saved. When editing, if host, account, secret, TLS and timeout are unchanged, scope and runtime limits can be saved directly. The server only re-probes after connection fields change; failures are never persisted.

Health check:

curl -fsS http://127.0.0.1:8111/healthz
# {"ok":true,"version":"1.1.1","db":"ok"}

Optional dependencies

uv sync --extra <name> trims the environment to "default dependencies + this one extra"; other installed clients are removed. Add --inexact when adding a single extra. Use --all-extras to install everything. Run these commands in the project directory used by uv run dr-panda-mcp.

When the console shows "client not installed", click Install. The service runs the command with --inexact in the current project and retests immediately; no restart is needed after a new client is installed.

# Config stores
uv sync --extra mysql --inexact       # asyncmy
uv sync --extra postgres --inexact    # asyncpg

# Troubleshooting components (GitLab and RabbitMQ need no extra)
uv sync --extra mongo --inexact
uv sync --extra redis --inexact
uv sync --extra kafka --inexact
uv sync --extra cls --inexact

# Everything at once
uv sync --all-extras

Deployment helper

For a new machine, use scripts/setup.sh instead of running the manual steps above:

./scripts/setup.sh check
./scripts/setup.sh install --method source --extras mysql,redis
sudo ./scripts/setup.sh service --dir /opt/dr-panda-mcp
./scripts/setup.sh start --dir /opt/dr-panda-mcp

It also supports PyPI installation (--method pypi --version 1.1.1), health checks, upgrades and a dedicated drpanda systemd user. See docs/deployment.md for details.

Files created by the first-run setup

After setup, data/ contains:

• Installation files are created with 0600 permissions.
• Back up secret.key, install.json, install.key and session.key together with the config store.
• Never commit data/ to Git.

Client setup

Configure the MCP URL and a bearer token in every client:

{
  "mcpServers": {
    "drpanda": {
      "url": "http://127.0.0.1:8111/mcp",
      "headers": {
        "Authorization": "Bearer <MCP token created on the My account page>"
      }
    }
  }
}

Cursor

Put the mcpServers block above into Cursor's MCP configuration file.

Codex

[mcp_servers.drpanda]
url = "http://127.0.0.1:8111/mcp"

[mcp_servers.drpanda.headers]
Authorization = "Bearer <token>"

DeepSeek Harness

Use serverName = drpanda; model-side tool names look like:

mcp__drpanda__mysql_query
mcp__drpanda__cls_search
mcp__drpanda__systems_status

Notes:

• /mcp returns 401 without a valid bearer token;
• a web login session cannot replace an MCP token;
• only token hashes are stored; the full value is shown once at creation and cannot be recovered (delete and create a new one if lost);
• if you change the port, update client URLs accordingly.

Targets and tools

A target belongs to an environment. Environments have a display title and a key. The title can change; the key is immutable and must be passed when troubleshooting. Different environments may contain targets with the same name; within one environment, multiple targets of the same type are distinguished by name and never selected automatically.

With a single environment, tools may omit environment; the migration creates default with the title Default. After adding more environments, every call must pass environment. Call systems_status without arguments to list environments, then pass the key to list targets in that environment. The web console switches targets by environment; disabled environments cannot be queried but their configuration is retained.

Tool calls only accept environment and target names — never hosts, accounts or passwords.

There is also an investigate_error prompt that organizes a troubleshooting path starting from an error symptom.

Target scope can only narrow the readable boundary:

• MySQL: databases / tables;
• MongoDB: databases / collections;
• Elasticsearch: indices;
• Redis: key prefixes / command scope;
• GitLab: projects / branches;
• RabbitMQ: vhosts / queues;
• Kafka: topics / partitions;
• CLS: log topics and time range.

Target names allow lowercase letters, digits and hyphens only, and are immutable. Secrets are stored encrypted and never echoed in lists.

Security model

Absolutely read-only

• Every tool across the eight components (including the web console's connection test) is read-only;
• accounts with write permissions are never used for writes;
• beyond the read-only whitelist, absolute dangerous rules reject:
  • admin/DDL/change commands;
  • unbounded scans, large aggregations, deep pagination, script execution, etc.;
• dangerous checks run before connecting; the rejection code is DANGEROUS_OPERATION;
• every call is bounded by timeout, row, byte and per-target concurrency limits; truncation is always marked.

Authentication and request protection

• Web login: administrator password plus an HMAC-signed session cookie;
• Forms: CSRF double-submit validation;
• /mcp: independent bearer tokens, stored as SHA-256 hashes;
• Host/Origin validation rejects unexpected origins;
• listens on loopback by default; changing to 0.0.0.0 or a specific interface IP exposes it, so an HTTPS reverse proxy is recommended;
• config-store changes are audited under the real administrator.

Frontend

• Jinja2 server-side rendering;
• core flows work without JavaScript;
• only small self-hosted, dependency-free scripts:
  • app.js: native <dialog> and form loading states;
  • copy-token.js: copy tokens;
• no frontend framework, Node build chain or third-party CDN;
• without JavaScript, dedicated form/confirmation pages or manual copy hints are shown — no fake buttons.

See Security and Verification for the full policy and boundaries.

System settings

Sign in and open /settings. Settings live in the config store with range validation; only actually changed values are written to audit and settings_history.

Settings can only adjust runtime policy; they cannot relax read-only rules, dangerous-operation rules, secret handling or target scope.

Environment variables

The repository ships .env.example with all defaults commented out; no configuration is required to start locally.

The service automatically loads ./.env from the current working directory; when the file is absent it falls back to environment variables and code defaults. To override defaults:

cp .env.example .env
# edit .env as needed (.env is ignored by git — do not commit it)
uv run dr-panda-mcp

Rules:

• precedence: real environment variables > .env > code defaults (systemd/Docker/CI variables always win);
• only the current directory's .env is read — no parent or home-directory lookup;
• overly open permissions (e.g. 0644), a non-regular file, or malformed lines abort startup, so secrets are not silently readable and configuration does not silently fail;
• there is no "disable auto-load" switch; simply do not mount .env in Docker/systemd.

Changing the listen address/port/public URL requires a process restart. Do not configure the config store through environment variables (see above).

Remote deployment:

• prefer an HTTPS reverse proxy; DR_PANDA_PUBLIC_URL only affects the displayed/copied address, not security policy;
• do not expose the console directly to the public internet; the first installation must still be completed on loopback;
• set DR_PANDA_TRUSTED_HOSTS (e.g. mcp.example.com) if you want an explicit /mcp Host allowlist;
• the real TLS setup behind the proxy still needs environment-specific validation.

Operations

Reset the administrator password

Run locally:

uv run dr-panda-mcp-admin reset-password

The reset increments auth_version, invalidating all existing web sessions; MCP tokens are unaffected.

SQLite backups

• automatic backups happen only when a pending Alembic migration exists;
• backups are written to data/backup/;
• retention is controlled by backup_keep_count;
• manual backups must include the config store and the four key/installation files.

Audit

• every tool call, target change and settings change is written to audit, including the environment;
• the web console's Audit page filters by time, action, environment and object; records cannot be deleted from the UI;
• audit retention defaults to 90 days and is checked hourly;
• cleanup only writes logs, never audit rows (to avoid self-amplification).

Development and testing

uv sync --all-extras --dev
uv run ruff check .
uv run pytest -q
uv run python scripts/smoke.py
uv run python scripts/check_docs_links.py

• tests use temporary SQLite databases and temporary keys, never real production systems;
• Docker integration scripts live under scripts/integration/;
• exact test counts are intentionally not hard-coded here; use the CI badge and your local run.

Project layout

src/dr_panda_mcp/
  __init__.py         process entrypoint
  cli.py              console entrypoints (loads ./.env)
  config.py           environment variables and runtime config
  setup.py            first-run setup wizard
  admin.py            local admin maintenance commands
  auth.py             passwords, sessions, CSRF, MCP tokens
  server.py           FastMCP, /mcp and web app assembly
  runtime.py          engine, migrations, secrets, ConfigStore
  settings.py         system settings defaults/ranges/groups
  connectors/         eight upstream connectors
  guards/             read-only whitelist and dangerous-operation rules
  tools/              MCP tool implementations and audit
  prompts.py          investigate_error
  web/                routes/templates/static/rendering
  store/              SQLAlchemy models, repository, Alembic migrations
tests/                unit, contract, web, tool and migration tests
docs/                 English documentation (default)
docs/zh-CN/           Chinese design and verification documents
scripts/              smoke tests, integration scripts and docs link check

Verified and unverified

Verified

• SQLite / MySQL / PostgreSQL config-store setup;
• creating, copying, deleting and paginating multiple MCP tokens;
• login, session, CSRF, logout and password change;
• target create/update/delete, enable/disable, connection test (test must pass before saving), secret encryption;
• same-origin async interactions: inline test/toggle, save gates, settings/login/password/setup feedback, with non-JS fallbacks;
• system settings save, per-item/global reset and history;
• light/dark themes, English/Chinese, 1440/390 responsive layouts;
• MySQL / Mongo / ES / Redis / RabbitMQ against real Docker upstreams;
• read-only guards, dangerous-command rejection, timeout/row/byte limits.

Unverified / boundaries

• Kafka end-to-end against a real upstream (image unavailable);
• CLS and GitLab end-to-end with real credentials;
• real HTTPS/TLS setup behind a reverse proxy;
• multi-user RBAC, OAuth/OIDC, MFA;
• password recovery page (only a local CLI reset exists);
• automatic recovery when install.json / install.key / secret.key are lost.

Unverified capabilities are never treated as available just because other components pass.

Documentation

English documentation:

• docs/README.md: English documentation index
• docs/architecture.md: components, request flow, data model and deployment
• docs/security.md: security model, authentication, secrets and remote access
• docs/ui-design.md: web console design system and page behavior
• docs/verification.md: testing strategy, verified and unverified capabilities
• docs/deployment.md: setup helper, systemd and first-install flow

The Chinese README links the Chinese design and verification docs.

Contributing, security and license

• CONTRIBUTING.md: development setup, tests, pull-request rules and bilingual docs sync
• SECURITY.md: how to report vulnerabilities and scope
• CODE_OF_CONDUCT.md: community expectations
• CHANGELOG.md: release history
• LICENSE: MIT

English is the default for code, comments, error codes and repository governance files. The UI and product docs also support Chinese; issues and pull requests may be written in English or Chinese.

If this project helps you, a star is appreciated.