// Set up and run a local Metabase instance. Downloads the JAR (if Java 21+ is available) or runs via Docker. Also handles stopping running instances.
| name | setup-metabase-instance |
| description | Set up and run a local Metabase instance. Downloads the JAR (if Java 21+ is available) or runs via Docker. Also handles stopping running instances. |
This skill helps users run a local Metabase instance for development, testing, or exploration.
This skill requires network access. All curl, java, and docker commands must be run outside the Cursor sandbox. Request full network access or run outside the sandbox before attempting these commands. Do not run them inside the sandbox as they will fail.
Run these checks in order. Stop at the first successful path.
Expand PATH first to avoid the macOS stub at /usr/bin/java:
export PATH=”/opt/homebrew/opt/openjdk/bin:/opt/homebrew/opt/openjdk@21/bin:/opt/homebrew/bin:/usr/local/opt/openjdk/bin:/usr/local/opt/openjdk@21/bin:/usr/local/bin:$PATH”
java -version 2>&1 | head -1
If the output shows Java 21 or higher → use Section A (JAR). Keep this PATH export for all subsequent commands.
If not found or version < 21 → check Docker (step 2).
docker --version 2>&1
If Docker is available: Use the Docker method (Section B).
If neither Java 21+ nor Docker is available: Direct the user to install Docker:
Tell them to re-run this skill after installing Docker.
ls -la ./metabase 2>/dev/null
If ./metabase exists and contains files, ask the user:
./metabase directory already exists. Should I use it (preserving existing data) or remove it and start fresh?"If the user wants to start fresh:
rm -rf ./metabase
mkdir -p ./metabase
Get the latest OSS release URL and download:
curl -sL -o ./metabase/metabase.jar https://downloads.metabase.com/latest/metabase.jar
Tell the user this may take a minute (the JAR is ~400MB).
lsof -i :3000 2>/dev/null | grep LISTEN
If the port is in use, ask the user:
Store the chosen port as $PORT (default: 3000).
Use the same PATH as in the Java prerequisite step when the agent uses a fresh shell (prepend the macOS Homebrew line again if unsure). Optionally set JAVA_CMD=$(command -v java) after that export so you invoke the same binary you version-checked.
export PATH="/opt/homebrew/opt/openjdk/bin:/opt/homebrew/opt/openjdk@21/bin:/opt/homebrew/bin:/usr/local/opt/openjdk/bin:/usr/local/opt/openjdk@21/bin:/usr/local/bin:$PATH"
cd ./metabase && \
MB_DB_FILE=./metabase.db \
MB_JETTY_PORT=$PORT \
nohup java -jar metabase.jar > metabase.log 2>&1 &
echo $! > metabase.pid
Tell the user: "Metabase is starting in the background. I'll check when it's ready..."
Also mention:
tail -f ./metabase/metabase.log"./metabase/metabase.pid"Poll the health endpoint every 5 seconds until it returns {"status":"ok"}:
curl -s http://localhost:$PORT/api/health
Keep polling until the response is {"status":"ok"}. Metabase usually starts within 30-60 seconds.
If the health check keeps failing after 2 minutes, check if the process is still running:
ps -p $(cat ./metabase/metabase.pid 2>/dev/null) > /dev/null 2>&1 && echo "Running" || echo "Not running"
tail -50 ./metabase/metabase.log
Once healthy, tell the user: "Metabase is ready at http://localhost:$PORT"
ls -la ./metabase 2>/dev/null
If ./metabase exists and contains files, ask the user:
./metabase directory already exists. Should I use it (preserving existing data) or remove it and start fresh?"If the user wants to start fresh:
rm -rf ./metabase
mkdir -p ./metabase
lsof -i :3000 2>/dev/null | grep LISTEN
If the port is in use, ask the user for an alternative port. Store as $PORT (default: 3000).
docker ps -a --filter "name=metabase-local" --format "{{.Names}} {{.Status}}"
If a container named metabase-local exists:
To remove an existing container:
docker rm -f metabase-local 2>/dev/null
The latest tag on Docker Hub is often outdated. Get the actual latest version from GitHub:
curl -s https://api.github.com/repos/metabase/metabase/releases/latest | grep '"tag_name"' | head -1
This returns something like "tag_name": "v0.52.5". Extract the version (e.g., v0.52.5).
Verify the Docker image exists:
docker manifest inspect metabase/metabase:$VERSION 2>&1 | head -5
If it doesn't exist, fall back to latest.
docker run -d \
--name metabase-local \
-p $PORT:3000 \
-v "$(pwd)/metabase:/metabase.db" \
-e MB_DB_FILE=/metabase.db/metabase.db \
-e MB_JETTY_HOST=0.0.0.0 \
-e MB_ENABLE_EMBEDDING_SDK=true \
-e MB_ENABLE_EMBEDDING_SIMPLE=true \
metabase/metabase:$VERSION
Tell the user: "Metabase is starting via Docker. I'll check when it's ready..."
Poll the health endpoint every 5 seconds until it returns {"status":"ok"}:
curl -s http://localhost:$PORT/api/health
Keep polling until the response is {"status":"ok"}. Metabase usually starts within 30-60 seconds.
If the health check keeps failing after 2 minutes, check the container status and logs:
docker ps --filter "name=metabase-local" --format "{{.Status}}"
docker logs metabase-local 2>&1 | tail -50
Once healthy, tell the user:
http://localhost:$PORT"docker logs -f metabase-local"Once the health check passes and Metabase is ready, ask the user:
"Would you like to set up the Metabase MCP so you can query your data directly from the IDE?"
If they agree, invoke the setup-metabase-mcp skill. The MCP setup will:
http://localhost:$PORT)If they decline, let them know they can set up the MCP later by asking for "Metabase MCP setup".
When the user asks to stop Metabase, determine which method was used.
if [ -f ./metabase/metabase.pid ]; then
kill $(cat ./metabase/metabase.pid) 2>/dev/null && rm ./metabase/metabase.pid && echo "Metabase stopped"
else
# Fallback: find by process
pkill -f "metabase.jar" && echo "Metabase stopped"
fi
docker stop metabase-local && echo "Metabase stopped"
To also remove the container (but keep data):
docker rm metabase-local
if [ -f ./metabase/metabase.pid ] && ps -p $(cat ./metabase/metabase.pid) > /dev/null 2>&1; then
echo "Metabase (JAR) is running with PID $(cat ./metabase/metabase.pid)"
else
echo "Metabase (JAR) is not running"
fi
docker ps --filter "name=metabase-local" --format "{{.Names}}: {{.Status}}"
These can be customized when starting Metabase:
| Variable | Default | Description |
|---|---|---|
MB_DB_FILE | ./metabase.db | H2 database file location |
MB_JETTY_PORT | 3000 | Port Metabase listens on |
MB_JETTY_HOST | localhost | Network interface (use 0.0.0.0 for Docker) |
For all options, see the Metabase Environment Variables documentation.
Another process is using the port. Either stop that process or choose a different port.
Install Java 21+ or use the Docker method instead.
You are likely hitting /usr/bin/java (stub). Prepend Homebrew OpenJDK to PATH as in Check for Java 21+, or call the real binary explicitly, e.g. /opt/homebrew/bin/java -version.
First startup takes longer as it initializes the database. Subsequent starts are faster.
Make sure Docker Desktop is running (macOS/Windows) or the Docker service is started (Linux).