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

Related MCP server: Looker MCP Server

Setup

1. Get Mode API credentials

Use a Member API key (recommended). Create your own under Workspace Settings > Personal > My API Keys and save the token and secret. Member keys respect your own Mode permissions, so the agent can only see and change what you can. If you can't create one, a Workspace admin needs to enable them under Workspace Settings > Features > API Keys > Member keys.

Mode also offers Workspace API tokens, created by admins under Workspace Settings > Privacy & Security > API. These act with admin access to the whole Workspace, so only use one if you need that — see Limitations / Safety below. (Older personal API tokens can no longer be created, but existing ones keep working.)

Both kinds of key expire after 90 days by default. When yours expires, the server reports "Authentication failed"; create a new key and update your MCP config.

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 Member API key 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

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