metabase-dataviewer MCP Service

An implementation of the Model Context Protocol (MCP) server designed for deep integration with Metabase business intelligence infrastructure.

This server, built using TypeScript, bridges AI assistants with the Metabase API, granting controlled access to analytical capabilities:

• Exposure of core Metabase constructs: Dashboards, reusable Questions/Cards, and underlying Databases.
• Provision of specialized routines for cataloging metadata and running ad-hoc data retrieval operations.
• Capability to ingest and process the structured data returned from Metabase executions.

Core Capabilities

Data Asset Exposition

• Catalog and reference Metabase assets using the metabase:// URI scheme.
• Direct access endpoints for reviewing presentation dashboards, parameterized questions, and source databases.
• Output serialization utilizes JSON format for maximum interoperability with downstream processing tools.

Analytical Routines

• list_dashboards: Retrieves a manifest of all available dashboards within the instance.
• list_cards: Fetches the registry of all defined questions or cards.
• list_databases: Provides an inventory of accessible underlying data sources.
• execute_card: Triggers the execution of a specific Metabase question/card, returning the resultant records.
• get_dashboard_cards: Retrieves the constituent cards belonging to a specified dashboard layout.
• execute_query: Enables running raw SQL commands against a designated Metabase-managed database.

Setup and Initialization

Prior to server operation, authentication parameters must be established via environment variables. Two primary authentication mechanisms are supported:

1. API Key Authentication (Recommended Priority):

   • METABASE_URL: Specifies the endpoint address of the Metabase installation (e.g., https://data.corp.com).
   • METABASE_API_KEY: The dedicated secret key for API access.

2. Credential Pair Fallback:

   • METABASE_URL: The target Metabase URL.
   • METABASE_USERNAME: The user login identifier.
   • METABASE_PASSWORD: The corresponding secret password.

The server prioritizes API Key validation. If METABASE_API_KEY is present, it will be used exclusively. Otherwise, it defaults to the username/password pair. Credentials via at least one path are mandatory for startup.

Example Environment Definition:

For API Key usage:

# Essential Configuration
export METABASE_URL=https://data.corp.com
export METABASE_API_KEY=super_secure_api_token_123

For Credentials fallback:

# Essential Configuration
export METABASE_URL=https://data.corp.com
export METABASE_USERNAME=analyst_user
export METABASE_PASSWORD=secret_pass_456

These variables can be persisted in shell profiles or managed using configuration file loaders like dotenv.

Development Lifecycle

Dependency installation:

npm install

Compiling the source code:

npm run build

For continuous development with automated recompilation:

npm run watch

Deployment

# Quick setup for automated environments
git clone https://github.com/imlewc/metabase-server.git && cd metabase-server && npm i && npm run build && npm link

To integrate this service with a local Claude Desktop instance, inject the following configuration snippet into your user-specific configuration file:

MacOS Location: ~/Library/Application Support/Claude/claude_desktop_config.json Windows Location: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "metabase-dataviewer": {
      "command": "metabase-server",
      "env": {
        "METABASE_URL": "https://data.corp.com",
        // Utilize API Key mechanism (preferred)
        "METABASE_API_KEY": "super_secure_api_token_123"
        // Alternative: Username/Password (if API Key is absent)
        // "METABASE_USERNAME": "analyst_user",
        // "METABASE_PASSWORD": "secret_pass_456"
      }
    }
  }
}

Note: System-level environment variable settings can supersede the values specified in this configuration file.

Installation via Smithery Registry

Automated provisioning for Claude Desktop via the Smithery registry:

npx -y @smithery/cli install @imlewc/metabase-server --client claude

Diagnostic Procedures

Debugging inter-process communication over stdio requires specialized tools. We strongly advocate for utilizing the MCP Inspector, which is accessible via a standard package script:

npm run inspector

The Inspector utility will yield a local URL to launch a debugging interface within a web browser.

Verification

Once environment variables are correctly established per the "Setup" section, manual authentication checks can proceed. The MCP Inspector is highly effective for probing server functionality.

1. Validating API Key Flow

1. Confirm METABASE_URL and a valid METABASE_API_KEY are active. Ensure credentials for the fallback method are deactivated.
2. Initiate the service: npm run build && node build/index.js (or the method utilized by your client).
3. Monitor server output for confirmation messages, such as: "Auth method confirmed: Metabase API Key."
4. Employ an MCP client or the Inspector to invoke a tool, e.g., a tool call targeting tools/call with payload {"name": "list_dashboards"}.
5. Validate the successful return of the expected data structure.

2. Validating Credential Fallback Flow

1. Ensure METABASE_API_KEY is unset.
2. Define METABASE_URL, METABASE_USERNAME, and METABASE_PASSWORD with active credentials.
3. Start the server process.
4. Examine server logs for indicators like: "Auth method confirmed: Username/Password." and subsequent connection attempts.
5. Test a routine call (e.g., list_dashboards) via an MCP client.
6. Confirm operation yields successful results.

3. Testing Failure Modes

• Invalid API Token: Set a known bad token while keeping username/password unset. Tool invocation should result in an error, likely logged as a Metabase API rejection (e.g., "401 Unauthorized from Metabase API").
• Invalid User Credentials: Disable API key usage. Use incorrect username/password combinations. Tool calls should fail, showing server-side logs indicating session establishment failure (e.g., "Authentication handshake failed.").
• Missing Credentials: If only METABASE_URL is present and no authentication secrets are defined, the server must refuse to initialize, logging a critical startup error detailing the missing authentication requirement (e.g., "FATAL: Server cannot start. Must supply API Key OR Username/Password pair alongside METABASE_URL.").

WIKIPEDIA: Business management tools encompass all systematic methods, applications, controls, computational solutions, and guiding principles employed by organizations to navigate market dynamics, maintain competitive parity, and enhance operational effectiveness. These tools span departmental needs—from planning and process optimization to data record-keeping, human resource management, and high-level strategic decision support. Modern business tooling has advanced rapidly due to technological leaps, making strategic selection and custom adaptation crucial for achieving sustained value, rather than simply adopting the newest available software.