### Quick Start with Environment Variables

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/README.md

Set Metabase URL and API key as environment variables before running the server. This is a common setup for quick deployment.

```bash
export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key
npx @easecloudio/mcp-metabase-server
```

--------------------------------

### Global Installation and Execution

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/README.md

Install the package globally for command-line access. Allows running the server command from any directory.

```bash
npm install -g @easecloudio/mcp-metabase-server
mcp-metabase-server
```

--------------------------------

### Run the project locally

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/CONTRIBUTING.md

Start the metabase-server MCP Server in development mode. This command is used to run the application locally after setup.

```bash
npm run dev
```

--------------------------------

### Install and Run Metabase MCP Server

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Installs the Metabase MCP Server package and runs it. The server listens on standard input/output.

```bash
npm install @easecloudio/mcp-metabase-server
npx @easecloudio/mcp-metabase-server
```

--------------------------------

### Install project dependencies

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/CONTRIBUTING.md

Install all necessary Node.js dependencies for the project using npm. This command should be run after cloning the repository.

```bash
npm install
```

--------------------------------

### Initialize and Run MetabaseServer

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Shows how to instantiate the MetabaseServer and start it, enabling it to listen for requests on standard input/output.

```typescript
const server = new MetabaseServer();
await server.run();  // Server listens on stdio
```

--------------------------------

### Check Metabase Configuration

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Verify that the METABASE_URL and METABASE_API_KEY environment variables are set correctly before starting the server.

```bash
echo "METABASE_URL=$METABASE_URL"
echo "METABASE_API_KEY=$METABASE_API_KEY"
```

--------------------------------

### TOOL_MODE Environment Variable Examples

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/configuration.md

Controls which tools are exposed to the MCP client. Examples show different modes like 'all', 'read', 'essential', and 'write'.

```bash
# Expose all tools (default)
TOOL_MODE=all
```

```bash
# Read-only mode (recommended for governance)
TOOL_MODE=read
```

```bash
# Essential workflow only
TOOL_MODE=essential
```

```bash
# Full write access
TOOL_MODE=write
```

--------------------------------

### Resource Handlers: ListResourceTemplates() Example Response

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/server-and-resources.md

Example response for listing resource URI templates supported by the server, including templates for dashboards, cards, and databases.

```json
{
  resourceTemplates: [
    {
      uriTemplate: 'metabase://dashboard/{id}',
      name: 'Dashboard by ID',
      mimeType: 'application/json',
      description: 'Get a Metabase dashboard by its ID'
    },
    {
      uriTemplate: 'metabase://card/{id}',
      name: 'Card by ID',
      mimeType: 'application/json',
      description: 'Get a Metabase question/card by its ID'
    },
    // ... more templates
  ]
}
```

--------------------------------

### Resource Handlers: ListResourcesRequest Example Response

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/server-and-resources.md

Example response structure for a ListResourcesRequest, detailing available dashboard resources.

```json
{
  resources: [
    {
      uri: 'metabase://dashboard/1',
      mimeType: 'application/json',
      name: 'Sales Dashboard',
      description: 'Metabase dashboard: Sales Dashboard'
    },
    {
      uri: 'metabase://dashboard/2',
      mimeType: 'application/json',
      name: 'Revenue Dashboard',
      description: 'Metabase dashboard: Revenue Dashboard'
    }
  ]
}
```

--------------------------------

### MetabaseServer.run()

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/server-and-resources.md

Starts the Metabase server and establishes a connection to the MCP transport. The server will continue running until explicitly stopped or the process terminates.

```APIDOC
## run()

### Description
Start the server and connect to MCP transport.

### Returns
Void (runs until explicitly stopped or process exits)

### Throws
Error if server fails to start

### Behavior
1. Creates StdioServerTransport
2. Connects MCP server to transport
3. Server is now ready to receive requests from MCP client

### Request Example
```typescript
const server = new MetabaseServer();
await server.run();  // Server runs until process is killed
```
```

--------------------------------

### loadConfig() Function Example

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/configuration.md

Example of loading Metabase configuration using the loadConfig function. It demonstrates the expected structure of the returned MetabaseConfig object when using an API key.

```typescript
import { loadConfig } from './utils/config.js';
const config = loadConfig();
// Returns:
// {
//   url: 'https://metabase.example.com',
//   apiKey: 'abc123...',
//   username: undefined,
//   password: undefined
// }
```

--------------------------------

### DatabaseSchema Example

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/schema-cache-reference.md

An example of the JSON structure for a cached database schema, showing metadata and table information.

```json
{
  "cached_at": "2026-01-15T10:30:00.000Z",
  "metabase_url": "https://metabase.example.com",
  "database_id": 1,
  "database_name": "Production",
  "tables": [
    {
      "id": 10,
      "name": "users",
      "display_name": "Users",
      "schema": "public",
      "fields": [
        {
          "id": 42,
          "name": "id",
          "display_name": "ID",
          "base_type": "type/Integer",
          "semantic_type": "type/PK"
        },
        {
          "id": 43,
          "name": "email",
          "display_name": "Email",
          "base_type": "type/Text",
          "semantic_type": "type/Email"
        }
      ]
    }
  ]
}
```

--------------------------------

### MetabaseServer run() Method

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/server-and-resources.md

Starts the MCP server and connects it to the transport layer. The server will run until explicitly stopped or the process exits.

```typescript
async run(): Promise<void>
```

```typescript
const server = new MetabaseServer();
await server.run();  // Server runs until process is killed
```

--------------------------------

### Clone the repository

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/CONTRIBUTING.md

Clone the metabase-server MCP Server repository to your local machine. This is the first step before installing dependencies.

```bash
git clone https://github.com/easecloudio/mcp-metabase-server.git
cd mcp-metabase-server
```

--------------------------------

### Loading .env file and running server

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/configuration.md

Commands to load environment variables from a .env file into the current shell session and then start the MCP Metabase Server.

```bash
source .env
npx @easecloudio/mcp-metabase-server
```

--------------------------------

### Execute Card Tool Call

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Example JSON payload for calling the 'execute_card' tool with a card ID and optional parameters to get query results.

```json
{
  "name": "execute_card",
  "arguments": {
    "card_id": 5,
    "parameters": []
  }
}
```

--------------------------------

### validateConfig() Function Example

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/configuration.md

Example of validating Metabase configuration using the validateConfig function. It shows a successful validation scenario and how to catch potential errors.

```typescript
import { validateConfig } from './utils/config.js';

try {
  validateConfig({
    url: 'https://metabase.example.com',
    apiKey: 'abc123'
  });
  console.log('Config is valid');
} catch (error) {
  console.error('Invalid config:', error.message);
}
```

--------------------------------

### Execute Query Tool Call

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Example JSON payload for calling the 'execute_query' tool with a database ID, SQL query, and optional parameters to get query results.

```json
{
  "name": "execute_query",
  "arguments": {
    "database_id": 1,
    "query": "SELECT * FROM users LIMIT 10",
    "parameters": []
  }
}
```

--------------------------------

### Development Build and Run Commands

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Common npm commands for installing dependencies, building, watching for changes, running the development server, and launching the MCP Inspector.

```bash
npm install                # Install dependencies
npm run build             # Compile TypeScript
npm run watch             # Incremental rebuild
npm run dev               # Build + start
npm run inspector         # Launch MCP Inspector (browser UI for debugging)
```

--------------------------------

### SQL to MBQL Conversion Example

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/schema-cache-reference.md

Demonstrates a multi-step process to convert a native SQL query to Metabase's MBQL format using the schema cache. This involves fetching a card, extracting the SQL, retrieving the schema cache with field IDs, and then constructing the MBQL query.

```typescript
const card = await client.getCard(5);
const sqlQuery = card.dataset_query.native.query;
// "SELECT user_id, COUNT(*) as count FROM orders GROUP BY user_id"
const databaseId = card.database_id;  // 1
```

```typescript
// Tool call: get_schema_cache { database_id: 1 }
const schema = {
  database_id: 1,
  database_name: "Production",
  tables: [
    {
      id: 10,
      name: "orders",
      fields: [
        { id: 42, name: "user_id", ... },
        { id: 43, name: "id", ... },
      ]
    }
  ]
};
```

```typescript
// Find field IDs in schema
const ordersTable = schema.tables.find(t => t.name === "orders");
const userIdFieldId = ordersTable.fields.find(f => f.name === "user_id").id;  // 42

// Build MBQL query
const mbql = {
  "source-table": 10,
  "aggregation": [["count"]],
  "breakout": [["field", 42, null]]
};
```

```typescript
const newCard = await client.createCard({
  name: "Order Count by User (MBQL)",
  dataset_query: {
    database: 1,
    type: "query",
    query: mbql
  },
  display: "table",
  visualization_settings: {},
  collection_id: 3
});
```

--------------------------------

### InvalidParams Example: Missing Required Parameters

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Example of a response when essential parameters are missing for a request, such as creating a card without specifying its query or display settings.

```json
{
  "code": "invalid_params",
  "message": "Required parameters missing"
}
```

--------------------------------

### Development Commands

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/README.md

Standard npm commands for installing dependencies, building, watching for changes, running in development mode, and launching the MCP Inspector for debugging.

```bash
npm install
```

```bash
npm run build       # compile TypeScript → dist/
```

```bash
npm run watch       # incremental rebuild
```

```bash
npm run dev         # build + start
```

```bash
npm run inspector   # launch MCP Inspector for debugging
```

--------------------------------

### Read Schema Cache Example

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/schema-cache-reference.md

Example of how to use the `readSchemaCache` function to retrieve cached database schema. Use this to check if a fresh cache is available before fetching new data.

```typescript
const cache = await readSchemaCache(
  'https://metabase.example.com',
  1
);

if (cache) {
  console.log(`Cache is fresh: ${cache.tables.length} tables`);
  // Use cache for field ID lookups
  const userId = cache.tables[0].fields.find(f => f.name === 'id')?.id;
  // MBQL reference: ["field", userId, null]
} else {
  console.log('Cache is missing or stale, need to fetch fresh');
}
```

--------------------------------

### SQL to MBQL Conversion - Get Card

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Step 1 of SQL to MBQL conversion: Retrieve a card to get its SQL query and database ID.

```text
Tool: get_card { card_id: 5 }
→ Response includes dataset_query.native.query and database_id
```

--------------------------------

### Run Metabase MCP Server CLI

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-overview.md

Execute the Metabase MCP Server as a Node.js CLI tool. This command starts the server, which then communicates with MCP clients over stdio.

```bash
npx @easecloudio/mcp-metabase-server
```

--------------------------------

### Environment Variables (.env file)

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/configuration.md

Example of a .env file for configuring the MCP Metabase Server. This file should be placed in the project root and sourced to load variables into the shell.

```dotenv
METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your_api_key_here
TOOL_MODE=all
```

--------------------------------

### Run Server with Read-Only Tool Mode

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Starts the MCP Metabase Server with the TOOL_MODE environment variable set to 'read', limiting exposed tools to read-only operations.

```bash
TOOL_MODE=read npx @easecloudio/mcp-metabase-server
```

--------------------------------

### Set METABASE_URL Environment Variable

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Example of setting the required METABASE_URL environment variable for server configuration. This is necessary for the server to connect to Metabase.

```bash
export METABASE_URL=https://metabase.example.com
```

--------------------------------

### Non-existent Resource Reference Example

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Illustrates the error response when referencing a resource (e.g., a card) that does not exist in Metabase. The server reports a 'Metabase API error'.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Metabase API error: Card not found"
    }
  ],
  "isError": true
}
```

--------------------------------

### InternalError Example: Authentication Failure Log

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Shows an example of an error log entry when authentication with Metabase fails due to invalid credentials. This error is typically thrown to the MCP client.

```json
{
  "timestamp": "2026-01-15T10:30:00.000Z",
  "level": "error",
  "message": "Authentication failed",
  "error": "401 Unauthorized"
}
```

--------------------------------

### Typo in Tool Name Example

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Demonstrates the response when a typo occurs in a tool name during a request. The server returns an 'Unknown tool' error.

```json
Request: call_tool { name: "list_dashbaords" }  // typo: dashbaords
Response: {
  "code": "method_not_found",
  "message": "Unknown tool: list_dashbaords"
}
```

--------------------------------

### List Dashboards Tool Call

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Example JSON payload for calling the 'list_dashboards' tool to retrieve an array of Dashboard objects.

```json
{
  "name": "list_dashboards",
  "arguments": {}
}
```

--------------------------------

### Docker Compose Configuration

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/configuration.md

Example Docker Compose file to set up the MCP Metabase Server alongside a Metabase instance. It defines environment variables for the server and links it to the Metabase service.

```yaml
version: '3'
services:
  mcp-server:
    build: .
    environment:
      METABASE_URL: http://metabase:3000
      METABASE_API_KEY: ${METABASE_API_KEY}
      TOOL_MODE: read
    depends_on:
      - metabase
  metabase:
    image: metabase/metabase:latest
    ports:
      - "3000:3000"
```

--------------------------------

### Invalid Metabase URL Format Example

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/configuration.md

Illustrates an incorrect format for the METABASE_URL environment variable. The URL must include a protocol like http:// or https://.

```bash
# Wrong
METABASE_URL=metabase.example.com
```

--------------------------------

### Launch MCP Inspector

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Start the MCP Inspector tool to debug requests and responses. It opens a browser UI that visualizes tool calls and their parameters.

```bash
npm run inspector
```

--------------------------------

### Dashboard Not Found Example

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Illustrates the error response when a requested dashboard does not exist. The tool handler catches a 404 error from the Metabase API and returns an 'internal_error'.

```json
Request: get_dashboard { dashboard_id: 99999 }
Metabase API returns: 404 Not Found
Tool handler catches Axios 404 error
Response: {
  "code": "internal_error",
  "message": "Metabase API error: Dashboard not found"
}
```

--------------------------------

### Initialize and Use MetabaseClient

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Demonstrates how to initialize the MetabaseClient with connection details and perform basic operations like fetching a dashboard, cards, or executing a query.

```typescript
const client = new MetabaseClient({
  url: 'https://metabase.example.com',
  apiKey: 'abc123'
});

const dashboard = await client.getDashboard(1);
const cards = await client.getCards();
const result = await client.executeQuery(1, 'SELECT * FROM users');
```

--------------------------------

### Get Dashboard Tool Call

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Example JSON payload for calling the 'get_dashboard' tool with a specific dashboard ID to retrieve a Dashboard object including its cards.

```json
{
  "name": "get_dashboard",
  "arguments": { "dashboard_id": 1 }
}
```

--------------------------------

### MetabaseClient Initialization

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/configuration.md

Shows how to initialize the MetabaseClient with a server configuration object.

```typescript
const metabaseClient = new MetabaseClient(serverConfig);
```

--------------------------------

### InvalidParams Example: Tool Not Available in TOOL_MODE

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Illustrates the error response when attempting to use a tool that is not permitted in the current TOOL_MODE environment, like trying to delete a dashboard in 'read' mode.

```json
{
  "code": "invalid_params",
  "message": "Tool not available in TOOL_MODE 'read': delete_dashboard"
}
```

--------------------------------

### SQL to MBQL Conversion - Get Schema Cache

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Step 2 of SQL to MBQL conversion: Fetch the schema cache for a given database ID to obtain field IDs for MBQL translation.

```text
Tool: get_schema_cache { database_id: 1 }
→ Response includes tables with fields and field IDs
```

--------------------------------

### Docker Deployment

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/README.md

Build a Docker image and run the Metabase MCP Server as a container. Mount environment variables for configuration.

```bash
docker build -t mcp-metabase-server .
docker run -it --rm \
  -e METABASE_URL=https://your-metabase-instance.com \
  -e METABASE_API_KEY=your_metabase_api_key \
  mcp-metabase-server
```

--------------------------------

### All Mode Configuration (Default)

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/server-and-resources.md

Sets the server to 'all' mode, exposing all available tools. This is the default mode, offering full access and maximum flexibility.

```shell
TOOL_MODE=all
```

--------------------------------

### Initialize MetabaseClient with API Key

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Use this to initialize the MetabaseClient when using an API key for authentication. Ensure the URL and apiKey are correctly provided.

```typescript
import { MetabaseClient } from './client/metabase-client.js';

const client = new MetabaseClient({
  url: 'https://metabase.example.com',
  apiKey: 'abc123def456'
});
```

--------------------------------

### Make a Generic API Call

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Use this method to make a generic API call to any Metabase endpoint. It supports GET, POST, PUT, and DELETE methods. For GET requests, data is passed as query parameters; for other methods, it's sent as the request body.

```typescript
async apiCall(
  method: "GET" | "POST" | "PUT" | "DELETE",
  endpoint: string,
  data?: any
): Promise<any>
```

```typescript
const results = await client.apiCall('GET', '/api/search', {
  q: 'revenue',
  models: 'card,dashboard'
});
```

--------------------------------

### MetabaseClient.url

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Gets the base URL of the Metabase instance the client is configured to connect to.

```APIDOC
## url (getter)

### Description
Get the base URL of the Metabase instance.

### Returns
The Metabase instance URL

### Example
```typescript
const client = new MetabaseClient({...});
console.log(client.url);  // "https://metabase.example.com"
```
```

--------------------------------

### MetabaseServer Constructor

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/server-and-resources.md

Initializes a new Metabase MCP server. It can be configured with an optional config object or loads settings from the environment.

```APIDOC
## new MetabaseServer(config?: MetabaseConfig)

### Description
Initialize a new Metabase MCP server.

### Parameters
#### Path Parameters
- **config** (MetabaseConfig) - Optional - Optional config object (if not provided, loads from environment)

### Request Example
```typescript
import { MetabaseServer } from './server.js';

// Load from environment
const server = new MetabaseServer();

// Or with explicit config
const server = new MetabaseServer({
  url: 'https://metabase.example.com',
  apiKey: 'abc123'
});
```
```

--------------------------------

### Get Metabase Permission Groups

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Use this method to retrieve a list of all available permission groups.

```typescript
async getPermissionGroups(): Promise<PermissionGroup[]>
```

```typescript
const groups = await client.getPermissionGroups();
groups.forEach(g => console.log(g.name));
```

--------------------------------

### McpError Class Example

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Demonstrates how to instantiate and throw a custom McpError. This is used when an invalid parameter is detected.

```typescript
throw new McpError(ErrorCode.InvalidParams, "card_id is required");
```

--------------------------------

### Correct Metabase URL Format

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Demonstrates the correct format for the METABASE_URL environment variable, which must include the protocol (e.g., https://).

```bash
# Wrong
export METABASE_URL=metabase.example.com

# Correct
export METABASE_URL=https://metabase.example.com
```

--------------------------------

### MetabaseServer Constructor

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/server-and-resources.md

Initializes a new Metabase MCP server. Can be configured with explicit settings or by loading from the environment.

```typescript
constructor(config?: MetabaseConfig)
```

```typescript
import { MetabaseServer } from './server.js';

// Load from environment
const server = new MetabaseServer();

// Or with explicit config
const server = new MetabaseServer({
  url: 'https://metabase.example.com',
  apiKey: 'abc123'
});
```

--------------------------------

### MetabaseClient Constructor

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Initializes a new Metabase API client with configuration including URL and authentication credentials (API key or username/password).

```APIDOC
## new MetabaseClient(config: MetabaseConfig)

### Description
Initializes a new Metabase API client.

### Parameters
#### Path Parameters
* `config` (MetabaseConfig) - Required - Configuration object with URL and auth credentials

### Request Example
```typescript
import { MetabaseClient } from './client/metabase-client.js';

const client = new MetabaseClient({
  url: 'https://metabase.example.com',
  apiKey: 'abc123def456'
});

// Or with username/password:
const client = new MetabaseClient({
  url: 'https://metabase.example.com',
  username: 'admin',
  password: 'password123'
});
```

### Behavior
- Creates Axios instance with base URL set to `config.url`
- If API key is provided: Sets `X-API-Key` header immediately
- If username/password provided: Prepares for lazy session token fetch on first API call
- Sets `Content-Type: application/json` header
```

--------------------------------

### Configure Metabase MCP Server Environment Variables

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Sets up required and optional environment variables for Metabase MCP Server configuration. METABASE_URL and METABASE_API_KEY are mandatory.

```bash
METABASE_URL=https://metabase.example.com
METABASE_API_KEY=your_api_key_here
TOOL_MODE=read  # essential, read, write, or all (default: all)
```

--------------------------------

### Get Specific Metabase Collection

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Fetch a single collection by its ID. Use this to retrieve details about a specific collection.

```typescript
async getCollection(id: number): Promise<Collection>

const collection = await client.getCollection(5);
console.log(collection.name, collection.color);
```

--------------------------------

### Get Specific Metabase User

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Use this method to retrieve a single user's details by providing their unique ID.

```typescript
async getUser(id: number): Promise<User>
```

```typescript
const user = await client.getUser(1);
console.log(user.email, user.is_superuser);
```

--------------------------------

### Get Metabase Users

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Use this method to list all users. Optionally, include deactivated users by setting the `includeDeactivated` parameter to true.

```typescript
async getUsers(includeDeactivated: boolean = false): Promise<User[]>
```

```typescript
const users = await client.getUsers(false);
users.forEach(u => console.log(u.email));
```

--------------------------------

### Get Metabase Database Metadata

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Retrieve comprehensive metadata for a database, including all its tables and fields. This is useful for understanding the database schema.

```typescript
async getDatabaseMetadata(id: number): Promise<any>

const metadata = await client.getDatabaseMetadata(1);
console.log(metadata.tables[0].fields);  // Array of field objects with IDs
```

--------------------------------

### Check Metabase Configuration

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Verify that essential environment variables for Metabase connection (METABASE_URL, METABASE_API_KEY) and tool mode (TOOL_MODE) are correctly set.

```bash
echo "METABASE_URL=$METABASE_URL"
echo "METABASE_API_KEY=$METABASE_API_KEY"
echo "TOOL_MODE=$TOOL_MODE"
```

--------------------------------

### Get All Tool Schemas

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/server-and-resources.md

Retrieves all available tool schemas, filtered according to the current TOOL_MODE. Useful for discovering available tools.

```typescript
getAllToolSchemas(): Tool[]
```

```typescript
const tools = registry.getAllToolSchemas();
console.log(tools.length);  // 96 if TOOL_MODE=all
tools.forEach(t => console.log(t.name, t.description));
```

--------------------------------

### Card Parameters

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/README.md

Tools for managing and retrieving information about card parameters, including getting available values and searching for parameter values.

```APIDOC
## Card Parameters

### Description
Tools for managing and retrieving information about card parameters, including getting available values and searching for parameter values.

### Tools
- `get_card_param_values`: Get available values for a card parameter
- `search_card_param_values`: Search / filter parameter values
- `get_card_param_remapping`: Get how parameter values are remapped for display
```

--------------------------------

### Claude Desktop Integration with Local Build

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/README.md

Configure Claude Desktop to use a locally built Metabase MCP Server. Specify the node command and the path to the JavaScript file.

```json
{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-server/dist/index.js"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}
```

--------------------------------

### Development and Testing Commands

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-overview.md

Common npm scripts for managing dependencies, building the project, running in development mode, and launching the MCP Inspector.

```bash
npm install              # Install dependencies
npm run build           # Compile TypeScript → dist/
npm run watch           # Incremental rebuild
npm run dev             # Build + start server
npm run inspector       # Launch MCP Inspector (browser UI)
```

--------------------------------

### refresh_schema_cache

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/schema-cache-reference.md

Force-refreshes the local schema cache for a specific database or all databases. This is useful when you suspect the cache might be outdated, for example, after a schema migration.

```APIDOC
## refresh_schema_cache

### Description
Force-refresh the local schema cache for one or all databases. Use when you suspect the cache is outdated (e.g. after a schema migration).

### Parameters
#### Query Parameters
- **database_id** (number) - Optional - ID of the database to refresh. Omit to refresh all cached databases.

### Response
#### Success Response
- **content** (array) - Tool response with refresh results summary
  - **type** (string) - "text"
  - **text** (string) - Summary of refresh results, indicating success/failure for each database.

### Response Example
```json
{
  "content": [{
    "type": "text",
    "text": "Schema cache refresh complete:\n✓ database 1 (\"Production\"): 45 tables\n✓ database 2 (\"Analytics\"): 32 tables\n\nCache location: /home/user/.easecloud/metabase-mcp/cache/a1b2c3d4e5f6/"
  }]
}
```

### Example
```json
// Refresh single database
{
  "tool": "refresh_schema_cache",
  "arguments": {
    "database_id": 1
  }
}

// Refresh all databases
{
  "tool": "refresh_schema_cache",
  "arguments": {}
}
```
```

--------------------------------

### Enable Detailed Logging

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Capture all server logs to a file for detailed error analysis. Use 'tail -f' to monitor the log file in real-time.

```bash
npx @easecloudio/mcp-metabase-server 2> /tmp/mcp-error.log
tail -f /tmp/mcp-error.log
```

--------------------------------

### API Key Authentication Configuration

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/README.md

Configure Metabase URL and API key using environment variables. This is the preferred method for authentication.

```bash
METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your_metabase_api_key
```

--------------------------------

### Initialize MetabaseClient with Username and Password

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Use this to initialize the MetabaseClient when using username and password for authentication. The client will automatically fetch a session token on the first API call.

```typescript
import { MetabaseClient } from './client/metabase-client.js';

const client = new MetabaseClient({
  url: 'https://metabase.example.com',
  username: 'admin',
  password: 'password123'
});
```

--------------------------------

### Authentication Error Message

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/configuration.md

Example of an error message indicating missing authentication configuration. This occurs when neither an API key nor a username/password combination is provided.

```text
Error: Either (METABASE_URL and METABASE_API_KEY) or (METABASE_URL, METABASE_USERNAME, and METABASE_PASSWORD) environment variables are required
```

--------------------------------

### Username and Password Authentication Configuration

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/README.md

Configure Metabase URL, username, and password using environment variables. This serves as a fallback authentication method.

```bash
METABASE_URL=https://your-metabase-instance.com
METABASE_USERNAME=your_username
METABASE_PASSWORD=your_password
```

--------------------------------

### Claude Desktop Configuration

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/configuration.md

JSON configuration for setting up the MCP Metabase Server within Claude Desktop. This includes specifying the command, arguments, and environment variables for the server.

```json
{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@easecloudio/mcp-metabase-server"],
      "env": {
        "METABASE_URL": "https://metabase.example.com",
        "METABASE_API_KEY": "your_api_key_here",
        "TOOL_MODE": "read"
      }
    }
  }
}
```

--------------------------------

### Get Specific Metabase Database

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Fetch details for a single database connection using its ID. Use this to inspect a specific database's configuration.

```typescript
async getDatabase(id: number): Promise<Database>

const db = await client.getDatabase(1);
console.log(db.engine);  // "postgres", "mysql", etc.
```

--------------------------------

### MetabaseClient.createDashboard

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Creates a new dashboard in Metabase with the provided data.

```APIDOC
## createDashboard(dashboard: Partial<Dashboard>)

### Description
Create a new dashboard.

### Parameters
#### Path Parameters
* `dashboard` (Partial<Dashboard>) - Required - Dashboard data (name required)

### Returns
Created Dashboard object with ID

### Throws
Axios error if validation fails

### Example
```typescript
const newDashboard = await client.createDashboard({
  name: 'Q1 Revenue',
  description: 'Q1 revenue metrics',
  collection_id: 5
});
console.log(newDashboard.id);  // Assigned ID
```
```

--------------------------------

### Get Metabase Instance URL

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Retrieve the base URL of the Metabase instance that the client is configured to connect to. This is useful for verifying the client's configuration.

```typescript
const client = new MetabaseClient({...});
console.log(client.url);  // "https://metabase.example.com"
```

--------------------------------

### Set Metabase Server URL

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/configuration.md

Configure the METABASE_URL environment variable to point to your Metabase instance. This is essential for the server to connect to Metabase.

```bash
METABASE_URL=https://metabase.example.com
```

--------------------------------

### Create a new user

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/tools-directory.md

Use `create_user` to add a new user to the system, requiring first name, last name, and email. Optional parameters include password and group IDs. This operation requires write or all mode.

```python
mcp.create_user(first_name='John', last_name='Doe', email='john.doe@example.com', group_ids=[1, 2])
```

--------------------------------

### Get collection details

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/tools-directory.md

Use `get_collection` to retrieve detailed information about a specific collection using its ID. This tool supports read, write, and all modes.

```python
mcp.get_collection(collection_id=1)
```

--------------------------------

### METABASE_USERNAME and METABASE_PASSWORD Environment Variables (Fallback)

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/configuration.md

Username and password for session-based authentication. Use this method if an API key is not available. Both variables are required if not using an API key.

```bash
METABASE_USERNAME=your_username
METABASE_PASSWORD=your_password
```

--------------------------------

### InvalidParams Example: Invalid Parameter Type

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Shows the error response when a parameter is provided with an incorrect data type, such as providing a string for a numerical card ID.

```json
{
  "code": "invalid_params",
  "message": "card_id must be a number"
}
```

--------------------------------

### Set Metabase Authentication Environment Variables

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Shows how to set environment variables for Metabase authentication. You can use either an API key or a username/password combination.

```bash
# Option 1: API Key
export METABASE_API_KEY=your_key_here

# Option 2: Username/Password
export METABASE_USERNAME=admin
export METABASE_PASSWORD=password123
```

--------------------------------

### Get Specific Dashboard by ID

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Retrieve details for a specific dashboard using its unique ID. This method returns a single Dashboard object with all its associated cards.

```typescript
const dashboard = await client.getDashboard(1);
console.log(dashboard.dashcards.length);  // Number of cards on dashboard
```

--------------------------------

### Run MCP Metabase Server with Write Access

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Execute the MCP Metabase Server with TOOL_MODE set to 'write' to allow modifications to Metabase dashboards and data. This is useful for AI assistants that need to create or update content.

```bash
TOOL_MODE=write npx @easecloudio/mcp-metabase-server
```

--------------------------------

### Claude Desktop Integration with npx

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/README.md

Configure Claude Desktop to use the Metabase MCP Server via npx. Specify command, arguments, and environment variables for connection.

```json
{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@easecloudio/mcp-metabase-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}
```

--------------------------------

### Tool Registry Operations

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Demonstrates how to retrieve all available tool schemas and handle a specific tool call using the ToolRegistry.

```typescript
const tools = registry.getAllToolSchemas();  // Get visible tools
const result = await registry.handleTool('list_dashboards', {});
```

--------------------------------

### Project Structure Overview

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-overview.md

Directory structure of the mcp-metabase-server project, showing the organization of source files, compiled output, and configuration.

```text
mcp-metabase-server/
├── src/
│   ├── index.ts                 # Entry point (CLI)
│   ├── server.ts               # Main MCP server class
│   ├── client/
│   │   └── metabase-client.ts  # Metabase HTTP client
│   ├── handlers/
│   │   ├── tool-registry.ts    # Tool routing
│   │   ├── dashboard-tools.ts  # Dashboard handlers
│   │   ├── card-tools.ts       # Card handlers
│   │   ├── database-tools.ts   # Database handlers
│   │   ├── table-tools.ts      # Table handlers
│   │   ├── schema-cache-tools.ts # Schema cache handlers
│   │   └── resource-handlers.ts # Resource URI handlers
│   ├── cache/
│   │   └── schema-cache.ts     # Local schema caching
│   ├── types/
│   │   ├── metabase.ts         # API type definitions
│   │   ├── errors.ts           # Error types
│   │   └── tool-metadata.ts    # Tool filtering metadata
│   └── utils/
│       └── config.ts           # Configuration loading
├── dist/                       # Compiled output
├── tsconfig.json
├── package.json
└── README.md
```

--------------------------------

### Get Metabase Schema Cache Path

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/schema-cache-reference.md

Retrieves the cache directory path for a specific Metabase instance. The path is derived from the Metabase URL and follows the format `~/.easecloud/metabase-mcp/cache/{12-char-url-hash}/`.

```typescript
export function getCachePath(metabaseUrl: string): string

```

```typescript
const path = getCachePath('https://metabase.example.com');
// Returns: "/home/user/.easecloud/metabase-mcp/cache/a1b2c3d4e5f6/"

```

--------------------------------

### InternalError Example: Metabase API Error Response

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/errors.md

Illustrates the response format when the Metabase API returns an error, such as an invalid card ID. The response includes an 'isError: true' flag.

```json
{
  "content": [{ "type": "text", "text": "Metabase API error: Card with ID 99999 not found" }],
  "isError": true
}
```

--------------------------------

### Essential Mode Configuration

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/server-and-resources.md

Sets the server to 'essential' mode, exposing only critical tools for minimal surface area and core functionality.

```shell
TOOL_MODE=essential
```

--------------------------------

### METABASE_API_KEY Environment Variable (Preferred)

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/configuration.md

API key for authentication. This is the preferred method for production use as it avoids password exposure and session token refresh.

```bash
METABASE_API_KEY=your_api_key_here
```

--------------------------------

### Set API Key Authentication

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Configures API Key authentication by setting the METABASE_API_KEY environment variable. This key is then used in the X-API-Key header.

```bash
METABASE_API_KEY=your_key_here
```

--------------------------------

### McpError Class Example

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-overview.md

Instantiate a custom error using the McpError class, providing an ErrorCode enum value and a descriptive message. This is used for custom error handling within the application.

```typescript
new McpError(ErrorCode.InvalidParams, "card_id is required")
```

--------------------------------

### getDatabases

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Lists all available database connections configured in Metabase.

```APIDOC
## getDatabases()

### Description
List all database connections.

### Method
GET

### Endpoint
`/api/database`

### Response
#### Success Response (200)
- **Array of Database objects** - Each object contains details like `name` and `engine`.

#### Response Example
```json
[
  { "id": 1, "name": "Main DB", "engine": "postgres" },
  { "id": 2, "name": "Analytics DB", "engine": "mysql" }
]
```
```

--------------------------------

### Get query metadata for a card's virtual table

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/tools-directory.md

Use `get_card_table_query_metadata` to fetch the query metadata for a virtual table belonging to a card. This operation is available in read, write, and all modes.

```python
mcp.get_card_table_query_metadata(card_id=123)
```

--------------------------------

### Get Specific Metabase Card

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Fetches a single card by its ID, including its full details such as the dataset query and display type. Use this to inspect or retrieve a specific card's definition.

```typescript
const card = await client.getCard(5);
console.log(card.dataset_query);  // The query definition
console.log(card.display);        // "table", "line", "bar", etc.
```

--------------------------------

### Set Username/Password Authentication

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/README.md

Configures Username/Password authentication by setting METABASE_USERNAME and METABASE_PASSWORD environment variables. The server then uses these to obtain a session token.

```bash
METABASE_USERNAME=admin
METABASE_PASSWORD=password123
```

--------------------------------

### Get FK relationships for a card's virtual table

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/tools-directory.md

Use `get_card_table_fks` to retrieve foreign key relationships associated with a virtual table of a specific card. This tool supports read, write, and all modes.

```python
mcp.get_card_table_fks(card_id=123)
```

--------------------------------

### Get cached schema with auto-fetch

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/tools-directory.md

Use `get_schema_cache` to retrieve the cached schema for a database, including tables and field IDs. It will automatically fetch the schema if it's stale. Supports essential, read, write, and all modes.

```python
mcp.get_schema_cache(database_id=1)
```

--------------------------------

### Claude Desktop Integration with Username/Password Fallback

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/README.md

Configure Claude Desktop to use the Metabase MCP Server with username and password authentication. This is a fallback if API keys are not used.

```json
{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@easecloudio/mcp-metabase-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_USERNAME": "your_username",
        "METABASE_PASSWORD": "your_password"
      }
    }
  }
}
```

--------------------------------

### Get Cached Schema for a Database

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/schema-cache-reference.md

Retrieves the cached schema for a specific database. If the cache is not found or is stale, it will automatically fetch fresh data from Metabase and cache it locally. Use this when you need the database schema for operations like SQL to MBQL conversion.

```typescript
private async getSchemaCache(args: any): Promise<any>
```

```typescript
{
  content: [
    {
      type: "text",
      text: JSON.stringify({
        ...schema,
        cache_status: "fresh" | "fetched_fresh"
      })
    }
  ]
}
```

```json
{
  "tool": "get_schema_cache",
  "arguments": {
    "database_id": 1
  }
}
```

```json
{
  "content": [{"type": "text", "text": "{\"cached_at\": \"2026-01-15T10:30:00.000Z\", \"database_id\": 1, \"database_name\": \"Production\", \"tables\": [...], \"cache_status\": \"fresh\"}"}]
}
```

--------------------------------

### Create Metabase User

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/api-reference-metabase-client.md

Use this method to create a new user. The `user` object must include `first_name`, `last_name`, and `email`.

```typescript
async createUser(user: Partial<User>): Promise<User>
```

```typescript
const newUser = await client.createUser({
  first_name: 'John',
  last_name: 'Doe',
  email: 'john@example.com'
});
```

--------------------------------

### ResourceHandlers.handleListResourceTemplates()

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/_autodocs/server-and-resources.md

Handles the listing of all supported resource URI templates. It returns an object containing an array of resource template definitions, each specifying a URI template, name, MIME type, and description.

```APIDOC
## handleListResourceTemplates()

### Description
List all resource URI templates.

### Returns
Object with `resourceTemplates` array

### Example Response
```typescript
{
  resourceTemplates: [
    {
      uriTemplate: 'metabase://dashboard/{id}',
      name: 'Dashboard by ID',
      mimeType: 'application/json',
      description: 'Get a Metabase dashboard by its ID'
    },
    {
      uriTemplate: 'metabase://card/{id}',
      name: 'Card by ID',
      mimeType: 'application/json',
      description: 'Get a Metabase question/card by its ID'
    },
    // ... more templates
  ]
}
```
```

--------------------------------

### Claude Desktop Integration with Tool Filtering

Source: https://github.com/easecloudio/mcp-metabase-server/blob/main/README.md

Configure Claude Desktop to use the Metabase MCP Server with 'essential' tool mode enabled. This limits the available tools for the AI.

```json
{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@easecloudio/mcp-metabase-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key",
        "TOOL_MODE": "essential"
      }
    }
  }
}
```