Mode Analytics MCP Server

An MCP server that lets you browse reports, manage queries, and fetch results from Mode Analytics from any MCP-compatible AI assistant or agent.

Tools

Setup

1. Get Mode API credentials

A Workspace admin creates the token in Mode under Workspace Settings > Privacy & Security > API: click the gear icon, choose Create new API token, and save the token and secret.

Mode no longer allows creating new personal API tokens (existing ones keep working). Workspace API tokens act with admin access to the whole Workspace, so treat them accordingly — see Limitations / Safety below.

2. Install uv

The server is launched with uvx, which comes with uv. Install it with brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh.

3. Add the server to your MCP client

The server runs over stdio via uvx mode-mcp. Add it to your MCP client's config; most clients use this mcpServers shape:

{
  "mcpServers": {
    "mode-analytics": {
      "command": "uvx",
      "args": ["mode-mcp"],
      "env": {
        "MODE_WORKSPACE": "your-workspace-name",
        "MODE_API_TOKEN": "${MODE_API_TOKEN}",
        "MODE_API_SECRET": "${MODE_API_SECRET}"
      }
    }
  }
}

uvx installs the package from PyPI on first run and reuses that version afterwards. To pick up new releases automatically, use "args": ["mode-mcp@latest"] instead.

The ${MODE_API_TOKEN} / ${MODE_API_SECRET} references are expanded from your shell environment by clients that support it, so no secrets land in the config file. Set them wherever you keep shell secrets, e.g. in ~/.zshrc:

export MODE_API_TOKEN="..."
export MODE_API_SECRET="..."

Env var syntax differs by client

Some clients expand ${VAR}, some use another syntax (e.g. ${env:VAR}), and some don't expand references at all; check your client's docs. If a reference isn't expanded, the server stops at startup with an error naming the variable, rather than failing later with a confusing authentication error.

Environment Variables

Choosing which tools are available

Disabled tools are never registered, so the agent doesn't see them at all.

• Default: everything except the two delete tools. The agent can browse, author, and archive, but can't permanently delete anything.
• Allow deletes: add "MODE_ENABLE_DELETES": "true" to env.
• Read-only: add "MODE_READ_ONLY": "true" to only allow browsing and fetching results.
• Anything else: list tool names in MODE_DISABLED_TOOLS.

A misspelled tool name in MODE_DISABLED_TOOLS stops the server with an error rather than silently leaving the tool enabled.

Limitations / Safety

No query execution. The server deliberately does not expose a "run this query" tool. The Mode API has no endpoint for running a single query — the only way to execute SQL is POST /reports/{token}/runs, which runs every query in the report at once. On reports with many or expensive queries, that's slow, costly, and impossible to predict from the agent's side. Instead, the server focuses on browsing, authoring, and fetching results:

• Write and manage SQL queries through your agent, then run them in Mode's UI where costs and side effects are visible.
• Use get_run_results to pull results from completed runs back into the conversation.

Deletes are permission-scoped, not owner-scoped. The server does not check who created a report or query; what you can delete is whatever your API token is allowed to delete in Mode. With a personal token that's limited to your own permissions, but a Workspace API token has admin access and can delete any report or query in the Workspace. That's why the delete tools are off unless you set MODE_ENABLE_DELETES=true.

Deletes can't skip the preview. When enabled, delete_report and delete_query are always two calls:

1. The first call deletes nothing. It returns a preview (the report's name, whether it's already archived, and its queries with who wrote each one; or a query's name, author, and SQL) plus a short confirm_code. Mode's API doesn't say who created a report, only who wrote each query.
2. The delete only happens when the same tool is called again with that confirm_code. The code is a fingerprint of what the preview showed, so it can't be guessed, and if the report or query changed after the preview (renamed, SQL edited, queries added), the code no longer matches and the delete is refused.

Archive instead of delete. archive_report hides a report and unarchive_report brings it back. The delete tool tells the agent to suggest archiving first.

Credentials never touch the committed config. The ${MODE_API_TOKEN} / ${MODE_API_SECRET} references in your MCP config are expanded from your shell environment at launch (in clients that support it), so the file is safe to commit. Keep the raw secrets in env vars and don't commit them.

Development

For maintainers (the source repo is private):

git clone git@github.com:nataliemona/mode_mcp.git
cd mode_mcp
uv sync --dev
uv run pytest