Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

docs - file-based development (#72496)

Jeff Bruemmera89d93d1f30a
diff --git a/docs/ai/file-based-development.md b/docs/ai/file-based-development.md
new file mode 100644
index 00000000000..f2f820c1268
--- /dev/null
+++ b/docs/ai/file-based-development.md
@@ -0,0 +1,203 @@
+---
+title: File-based development
+summary: "Use a combination of agent skills, the Metabase MCP server, and serialization to develop Metabase content with agents on your local file system."
+---
+
+# File-based development
+
+{% include plans-blockquote.html feature="File-based development" %}
+
+Metabase content like questions and dashboards can be serialized as YAML files. You can edit those YAML files directly, but the most productive workflow is to let an agent do the editing for you — this article focuses on that agent-driven workflow.
+
+## The file-based toolkit
+
+We provide a set of tools for using an AI agent to create and edit Metabase content [serialized](../installation-and-operation/serialization.md) as YAML files.
+
+- The [Metabase Representation Format](https://github.com/metabase/representations). This is a directory that includes a spec, schemas, and examples for all Metabase entities as YAML files: questions, dashboards, and so on.
+- The [`metabase-representation-format` agent skill](https://github.com/metabase/agent-skills) for working with these YAML files.
+- CLI commands and API endpoints to export and import content serialized in YAML.
+- [MCP server](./mcp.md) to look up database metadata when creating the YAML files.
+
+## Prerequisites
+
+### Set up a development Metabase
+
+Set up a Metabase instance to check your work before pushing changes to production. This Metabase should connect to the same data warehouse(s) your production Metabase connects to. A [config file](../configuring-metabase/config-file.md) will come in handy here.
+
+We also recommend turning off the sample content and usage analytics, so they don't pollute the data model. If you're using a [docker compose file](../installation-and-operation/running-metabase-on-docker.md), add these [environment variables](../configuring-metabase/environment-variables.md):
+
+```
+MB_LOAD_SAMPLE_CONTENT: "false"
+MB_INSTALL_ANALYTICS_DATABASE: "false"
+```
+
+### For agent-driven development
+
+If you want an agent to do the editing, you also need:
+
+1. **The `metabase-representation-format` skill added to your agent** so the agent understands the YAML schemas. See [Agent skills](https://github.com/metabase/agent-skills).
+
+2. **Your agent connected to your Metabase's MCP server**, so it can look up database metadata (table names, fields, and sample values) when writing questions and dashboards. The MCP server exposes tools like `search`, `get_table`, and `get_table_field_values`. See [MCP server](./mcp.md).
+
+## Example agent-driven workflow
+
+Here's an example workflow for using an agent to create Metabase content as YAML on your local machine, then importing that content into your development and production Metabases.
+
+### 1. Create a git repo
+
+Initialize a git repo with a README.md and an initial commit.
+
+### 2. Check out a branch
+
+Create a new branch to track your work.
+
+```
+git checkout -b your-branch-name
+```
+
+### 3. Export your production Metabase
+
+Always export before editing YAML files locally. If someone has updated a dashboard or question in the Metabase UI since your last export, and you edit and import stale local files, the import will overwrite those in-app changes. Re-export at the start of each editing session if the app may have changed since your last export.
+
+Your agent will also read these serialized YAML files to find info about existing content, so the agent can know what you mean when you ask it to "add the new question to the Handsome collection."
+
+To export your Metabase:
+
+1. Create an [API key](../people-and-groups/api-keys.md).
+2. Assign the key to the Admin group.
+3. Send a `curl` request to export data:
+
+ ```sh
+ curl \
+ -H 'X-API-Key: YOUR_API_KEY' \
+ -X POST 'https://your-metabase-url/api/ee/serialization/export?data_model=false' \
+ -o metabase_data.tgz
+ ```
+
+ substituting `YOUR_API_KEY` with your API key and `your-metabase-url` with the URL of your Metabase instance.
+
+ Be sure to set the `data_model=false` query parameter excludes the data model from the export, since the data model payload can be large. Instead, your agent will use the MCP server to search for the metadata it needs to generate the YAML files. See [Serialization](../installation-and-operation/serialization.md) for other export options.
+
+ This command will download the files as a GZIP-compressed Tar file named `metabase_data.tgz`.
+
+4. Extract the archive:
+
+ ```sh
+ tar -xzf metabase_data.tgz
+ ```
+
+Instead of running this `curl` by hand every time, you can ask your agent to generate an `export.sh` script that wraps the `curl` and the `tar -xzf` extraction, so you can re-export with a single command.
+
+### 4. Commit the export
+
+Commit the initial exported set of YAML files. If your AI goes off the rails, you can always revert to the original export.
+
+### 5. Use AI to edit or create new content
+
+Change into the directory with your serialized files and ask your agent to create whatever you want. Make sure your agent actually invokes the skills, otherwise the agent may not get the YAML format right.
+
+Example prompt:
+
+```
+Use the metabase-representation-format skill and the Metabase MCP server to do the following by editing the YAML files in this directory:
+
+1. Create a new collection called "File-based collection".
+2. Create a new dashboard called "AI-created dashboard", saved to that collection.
+3. Create a question called "AI counts products" that counts the number of products by category.
+4. Add that question to the "AI-created dashboard".
+```
+
+Depending on how sophisticated your AI model is, you can also try more ambitious, open-ended requests:
+
+```
+Use the metabase-representation-format skill and the Metabase MCP server to analyze the data in the sample postgresql
+database. Look at the orders, people, reviews, and products tables.
+
+Create a dashboard with some questions that gives an overview of how the business is doing.
+```
+
+### 6. Validate the YAML files
+
+Before importing, check your YAML files against the representation schemas. The `metabase-representation-format` skill should have the agent run the validator for you, but you can also run it yourself:
+
+```
+npx --yes @metabase/representations validate-schema
+```
+
+You can also set up a workflow to run the validator on pull requests. Here's an example, saved to `.github/workflows/schema-check.yml`:
+
+```yaml
+name: Schema Check
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+
+jobs:
+ schema-check:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: actions/setup-node@v4
+ with:
+ node-version: "20"
+
+ - name: Validate representation YAML files
+ run: npx --yes @metabase/representations validate-schema
+```
+
+That way your team catches schema issues on the PR, before anyone imports the changes into Metabase.
+
+### 7. Import the changes to your development Metabase
+
+Import your changes to your development Metabase, and check that the import works and the content is as expected.
+
+First, compress your directory of YAML files:
+
+```
+tar -czf metabase_data.tgz metabase_data
+```
+
+Then import that compressed file:
+
+```
+curl -X POST \
+ -H 'X-API-Key: YOUR_API_KEY' \
+ -F 'file=@metabase_data.tgz' \
+ 'https://your-metabase-url/api/ee/serialization/import' \
+ -o -
+```
+
+The `-o -` flag writes the import response to stdout, so you can see whether the import succeeded and check any warnings.
+
+Just like with export, you can ask your agent to generate an `import.sh` script that handles the `tar -czf` compression and the `curl` in one shot.
+
+Log in to this Metabase and check that the changes are as you expect.
+
+#### Did your AI go off the rails?
+
+If you want to undo the agent's changes, use `git` to revert your YAML files to the last known-good commit. Don't try to undo the changes by re-exporting from your production Metabase: re-exporting will overwrite edits you made to existing files, but it _won't_ delete any new files the agent created, so your directory will still contain those unwanted files.
+
+### 8. Commit your changes
+
+If all looks good, commit your changes. If you get any errors, give the error info to the agent in the same session and the agent should iron out any issues.
+
+### 9. Import to your production Metabase
+
+Import your changes via the API, push your changes to a remote git repository and set up [remote sync](../installation-and-operation/remote-sync.md) so that your production instance pulls in the changes automatically.
+
+## Deleting content
+
+Since imports and exports _don't_ delete content, you'll need to delete that content in the Metabase application itself, then update the YAML files as well.
+
+1. Delete the content in your production Metabase (in the app's UI itself).
+2. Export from your production Metabase to your repo.
+3. Commit the changes so that the YAML files are updated. That way Metabase won't recreate the deleted items the next time you import your changes.
+
+## Further reading
+
+- [MCP server](./mcp.md)
+- [Serialization](../installation-and-operation/serialization.md)
+- [Agent skills](https://github.com/metabase/agent-skills)
diff --git a/docs/ai/mcp.md b/docs/ai/mcp.md
index 5b11a023f07..0d79385ea8f 100644
--- a/docs/ai/mcp.md
+++ b/docs/ai/mcp.md
@@ -38,6 +38,18 @@ A first-time connection will go something like this:
Results returned by the MCP server are sent to your MCP client, which may forward them to an AI provider depending on how the client is configured. See [Privacy](./settings.md#privacy).
+### Site URL must match the URL your client uses
+
+For containerized setups, like when testing locally, you may need to set the `MB_SITE_URL` environment variable to the URL you point to. For example, if you're playing around with a Metabase on localhost:
+
+```
+MB_SITE_URL: http://localhost:3000
+```
+
+Some explanation: OAuth discovery starts with Metabase returning a `WWW-Authenticate` header whose `resource_metadata` URL is built from your **Site URL** setting in **Admin** > **Settings** > **General** (or via the environment variable).
+
+If the site URL doesn't match an address your MCP client can reach, like if you're running Metabase in Docker and the site URL got auto-detected from an internal hostname like `metabase-dev:3000`, the client will register but fail the handshake. Your MCP client will typically report a connection failure rather than prompting you to authenticate (for example, Claude Code shows `✗ Failed to connect` rather than `! Needs authentication`).
+
## 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.md), and exposes the following tools. If you're building a custom integration and need full control, use the [Agent API](./agent-api.md) directly instead.
@@ -51,8 +63,15 @@ Some clients (like Claude Desktop) will ask you to approve each tool the first t
- **execute_query**: Execute a previously constructed query and return the results with column metadata, row count, and execution time.
- **query**: Query a table or metric and return results.
+## Use the MCP server with file-based 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.md).
+
## Further reading
- [Agent API](./agent-api.md)
+- [File-based development](./file-based-development.md)
- [Metabase API docs](../api.html)
- [Model Context Protocol specification](https://modelcontextprotocol.io/)