Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion _data/shared_chrome.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"$schema": "https://www.metabase.com/shared/chrome.schema.json",
"version": 1,
"generated_at": "2026-06-10T04:52:16+00:00",
"generated_at": "2026-06-10T20:05:19+00:00",
"origin": "https://www.metabase.com",
"stylesheets": [
{
Expand Down
Binary file added _docs/latest/ai/images/mcp-chart.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
40 changes: 29 additions & 11 deletions _docs/latest/ai/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ latest: true

Metabase includes an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server (using Streamable HTTP transport) that lets AI clients connect directly to your Metabase, all scoped to the connecting person's permissions.

# Enable MCP server
## Enable MCP server

_Admin > AI > MCP_

Expand All @@ -33,7 +33,7 @@ Under **Supported MCP clients**, switch on any clients you want to allow:

- **Claude** (Claude Desktop and Claude on the web)
- **Cursor and VS Code**
- **ChatGPT**
- **ChatGPT**, including **Codex**

Toggling on a client automatically adds that client's sandbox domains to Metabase's CORS allowlist, which is what lets browser-based MCP clients make cross-origin requests to your Metabase.

Expand All @@ -49,23 +49,25 @@ https://mcp.internal.example.com https://*.staging.example.com

The field accepts wildcards (`*`) for subdomains. Changes take effect in about a minute. Might be a good time to get up and pour yourself a glass of water.

## Connect an MCP client
## Connect a client to your Metabase MCP server

If your admin has turned on [your Metabase's MCP server](#enable-mcp-server), all you need to do is point your MCP client at Metabase's MCP endpoint, `/api/metabase-mcp`. For example:

```
https://{your-metabase.example.com}/api/metabase-mcp
```

In the terminal, for example, you can run the following command.
You can find your instance's MCP URL in **Admin > AI > MCP**.

For Claude Code, for example, you can run the following command.

```
claude mcp add --transport http metabase https://{your-metabase-url}/api/metabase-mcp
```

Replacing {your-metabase-url} with your Metabase address. Once added, Claude Code will handle the OAuth flow for you:
replacing {your-metabase-url} with your Metabase address.

For Claude Desktop, you can create a [custom connector](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) by just giving it that URL to your Metabase's mcp endpoint.
Once you add the MCP server, your client will direct you to authentication page for your Metabase instance.

## Authentication

Expand Down Expand Up @@ -102,35 +104,51 @@ For example, if you ask your AI client to use your Metabase's MCP server "what's

You don't need to have an [AI provider](settings#choose-ai-provider) configured in Metabase to use your Metabase's MCP server. If you _do_ have an AI provider configured in Metabase to power Metabot, that provider will _not_ be used for MCP server requests. MCP calls by your local client have no effect on token usage for your Metabase's AI connection.

## Using the MCP server


The MCP server will return results as either text or an inline chart, depending on the question you asked.

If you want the MCP server to return an inline chart, ask it to "show" or "visualize" the data:

![Show me the stuff](./images/mcp-chart.png)

Currently, the Metabase MCP server supports bar and line charts. You can drill-through through the charts, change time granularity, or explore them in Metabase.

If your client is connected to other MCP servers, you can asks questions that combine data from multiple sources. For example, you can ask a question about your customers that combines data from Metabase, your CRM, and your support ticket platform (Though maybe you should put all that data into your Metabase).

See [Available tools](#available-tools) for the list of functionality supported by the MCP server.

## Available tools

Some clients (like Claude Desktop) will ask you to approve each tool the first time it's used. The MCP server builds on Metabase's [Agent API](./agent-api), and exposes the following tools. If you're building a custom integration and need full control, use the [Agent API](./agent-api) directly instead.

### Discovery and reading
#### Find and read content

- **search**: Find tables, metrics, cards, dashboards, and collections using keyword or natural language search.
- **read_resource**: Read one or more Metabase entities by `metabase://` URI. Covers database / schema / table / collection / card / dashboard / metric / transform navigation in a single tool. Up to 5 URIs per call.

### Query construction and execution
#### Query and visualize data

- **construct_query**: Construct a query against a table or metric. Returns an opaque query handle that can be passed to `execute_query`.
- **query**: Query a table or metric and return results.
- **execute_query**: Execute a previously constructed query and return the results with column metadata, row count, and execution time.
- **execute_sql**: Execute a raw SQL query against a database. Requires native-query permission on the target database. An admin can disable this tool instance-wide via the `mcp-execute-sql-enabled` setting.
- **visualize_query**: render a chart inline in your AI client (bar or line chart only).

### Writing
#### Create content

- **create_question**: Save a query as a named question (card).
- **update_question**: Update a saved question. Setting `collection_id` moves the card to another collection.
- **create_dashboard**: Create a new dashboard, optionally populated with saved questions.
- **update_dashboard**: Update a dashboard's metadata (name, description, collection, archived).
- **create_collection**: Create a new collection, optionally nested under a parent collection.

## Use the MCP server with file-based development
## Use the MCP server with agent-driven development

You can use the MCP server to help you create Metabase content as serialized YAML files that you can import into your Metabase. Point your agent at the MCP server to give it access to your Metabase's database metadata (table names, fields, and sample values) so it can write questions and dashboards that point at real columns.

See [File-based development](./file-based-development).
See [Agent-driven development](./file-based-development).

## Further reading

Expand Down
6 changes: 4 additions & 2 deletions _docs/latest/data-modeling/json-unfolding.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,16 +34,18 @@ And here are the values as seen in the table:

This unfolding allows you to filter for values found in the original JSON object.

Metabase can also unfold nested JSON objects, but it doesn't unfold arrays. If a key contains an array, Metabase keeps that array as a single field.

Metabase will prefix the unfolded column names with the name of the original column that contained the JSON. You can change the column names in **Admin** > [Table metadata](metadata-editing), or by creating a [model](./models) and editing the column metadata.

## Databases that support JSON unfolding

- [BigQuery](../databases/connections/postgresql): automatically enabled, applies to `STRUCT` types only.
- [BigQuery](../databases/connections/bigquery): automatically enabled, applies to `STRUCT` types only.

If your data is stored in the [STRUCT data type](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#struct_type) in BigQuery, you can query the table's nested fields. This is enabled by default. However, Metabase won't unfold JSON stored in BigQuery as the `JSON` type. This is because in BigQuery, nested fields are _part of the table definition itself_, so when Metabase syncs with your BigQuery database, it'll be able to get metadata about any of your tables, including tables with nested fields. Querying nested fields, however, doesn't extend to arrays (REPEATED (STRUCT)) in BigQuery.

- [Druid (JDBC)](../databases/connections/druid)
- [MongoDB](../databases/connections/mysql): automatically enabled for all nested fields.
- [MongoDB](../databases/connections/mongodb): automatically enabled for all nested fields.
- [MySQL](../databases/connections/mysql)
- [PostgreSQL](../databases/connections/postgresql)

Expand Down
86 changes: 86 additions & 0 deletions _docs/latest/installation-and-operation/alert-management.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
---
version: v0.62
has_magic_breadcrumbs: true
show_category_breadcrumb: true
show_title_breadcrumb: true
category: Installation and Operation
title: Alerts management
source_url: >-
https://github.com/metabase/metabase/blob/master/docs/installation-and-operation/alert-management.md
layout: new-docs
summary: See all alerts in your instance and manage them in bulk
latest: true
---

# Alerts management

_Admin > Tools > Alerts management_

In the Alert management section, Admins can:

- View and search all [question alerts](../questions/alerts) in their Metabase
- Identify failed or orphaned alerts
- Edit alerts, including changing the alert's owner
- Delete alerts in bulk

![Alert management](./images/alert-management.png)

Currently, [dashboard subscriptions](../dashboards/subscriptions) are not included.

## See all alerts

To see all alerts active in your Metabase instance, go to **Admin > Tools > Alerts management**.

You can:

- Filter alerts by channel ([email](../configuring-metabase/email), [Slack](../configuring-metabase/slack), or [webhook](../configuring-metabase/webhooks)) or recipient.

- See alerts that **failed** the last time they were ran.

Failed alerts view include both alerts that were attempted but failed (for example, because of a query error) and alerts that were abandoned and never attempted (for example, because the instance was restarting at the moment when the alert was scheduled).

To see the entire history of alert runs (not just the last attempt), go to **Admin > Tools > Tasks** instead.

- See **ownerless** alerts - alerts whose owner has been deactivated

This is helpful when you want to [mass-delete](#delete-alerts) alerts that are no longer relevant, or [change the owner](#change-alert-owners) to an active user.

- See individual alert's properties and history.

- [Delete alerts in bulk](#delete-alerts).

- [Change alert owners in bulk](#change-alert-owners).

If you want to get some analytics about your alerts (rather than manage them) - for example, you want to see how many alerts have failed per week, or which questions have the most number of alerts - use [Usage Analytics](../usage-and-performance-tools/usage-analytics) instead.

## Change alert owners

The owner of an alert has the power to edit or delete the alert. Usually, the person who created the alert is also the alert's owner.

Admins can change owners of alerts. This is useful, for example, if the original alert owner left the company, and you need to give some else the power to manage the alert.

To change the owner for one or more alerts:

1. Go to **Admin > Tools > Alerts management**.
2. Select the alerts whose owners you'd like to change.
3. Click **Change owner** at the bottom of the screen.
4. Assign a new owner.

## Delete alerts

![Bulk delete](./images/alerts-bult.png)

You can delete multiple alerts at once.

1. Go to **Admin > Tools > Alerts management**.
2. Select the alerts whose owners you'd like to delete.
3. Click **Delete** at the bottom of the screen.

## Further reading

- [Alerts](../questions/alerts)
- [Usage analytics](../usage-and-performance-tools/usage-analytics)
- [Setting up email](../configuring-metabase/email)
- [Setting up Slack](../configuring-metabase/slack)
- [Setting up webhooks](../configuring-metabase/webhooks)
- [Managing people](../people-and-groups/managing)
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
24 changes: 13 additions & 11 deletions _docs/latest/questions/alerts.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,13 +42,13 @@ To create an alert:
2. Click on the **three dots** in the top-right of the screen.
3. Select **Create an alert**.
4. Select what you want to be alerted about (options depend on the question type):
- [When a question returns a result](#results-alerts) - for any question.
- [When a time series crosses a goal line](#goal-line-alerts) - for a line, bar, or area chart displaying a time series.
- [When a progress bar reaches or goes below its goal](#progress-bar-alerts) - for progress bars.
6. Select when you want Metabase to check the results: by the minute, hourly, daily, weekly, monthly, or on a custom schedule that you set using the Quartz [cron syntax](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html).
7. Select the alert's destination: [email](../configuring-metabase/email), [Slack](../configuring-metabase/slack), or to a [webhook](../configuring-metabase/webhooks) (only admins and people with [settings access](../permissions/application#settings-access) can create and send to webhooks).
8. Configure any other options (like [only sending the alert once](#send-a-one-time-alert)).
9. Click **Done**.
- [When a question returns a result](#results-alerts) - for any question.
- [When a time series crosses a goal line](#goal-line-alerts) - for a line, bar, or area chart displaying a time series.
- [When a progress bar reaches or goes below its goal](#progress-bar-alerts) - for progress bars.
5. Select when you want Metabase to check the results: by the minute, hourly, daily, weekly, monthly, or on a custom schedule that you set using the Quartz [cron syntax](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html).
6. Select the alert's destination: [email](../configuring-metabase/email), [Slack](../configuring-metabase/slack), or to a [webhook](../configuring-metabase/webhooks) (only admins and people with [settings access](../permissions/application#settings-access) can create and send to webhooks).
7. Configure any other options (like [only sending the alert once](#send-a-one-time-alert)).
8. Click **Done**.

## Send a one-time alert

Expand Down Expand Up @@ -85,11 +85,11 @@ To create an alert when a time series crosses a goal line:
5. Save the question.
6. Click the **three dots** icon in top and select "Create alert"

You can choose:
You can choose:

- Whether you want Metabase to alert you when the time series goes above the goal line or when it goes below the goal line.
- Whether you want Metabase to alert you every time the time series crosses a goal line, or only the first time it crosses the goal line.
- How often you want Metabase to check to see if the goal line has been crossed.
- Whether you want Metabase to alert you when the time series goes above the goal line or when it goes below the goal line.
- Whether you want Metabase to alert you every time the time series crosses a goal line, or only the first time it crosses the goal line.
- How often you want Metabase to check to see if the goal line has been crossed.

7. Select the schedule and recipients for the alert, and click "Done"

Expand Down Expand Up @@ -126,6 +126,8 @@ Admins:
- Admins can add or remove recipients on any alert, even ones that they didn't create themselves.
- Admins can bulk manage alerts per person from the [People menu in Admin settings](../people-and-groups/managing#unsubscribe-from-all-subscriptions-and-alerts).

- Admins can bulk manage all alerts in the instance in [Admin > Tools > Alert management](../installation-and-operation/alert-management).

Metabase will email you when:

- You set up an alert
Expand Down
Binary file added _docs/v0.62/ai/images/mcp-chart.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading