AI Bridge for Metabase Analytics (MCP Server)

This implementation serves as a Model Context Protocol (MCP) gateway, establishing a robust connection between large language models and the Metabase data visualization ecosystem. It functions as the intermediary, translating natural language requests into actionable calls against the Metabase API.

System Synopsis

This specialized MCP server bridges conversational AI capabilities with your organization's Metabase infrastructure. It enables LLMs equipped with MCP functionality to directly interrogate and manipulate analytical assets, acting as a secure data proxy.

Core Capabilities

• Asset Navigation: Traverse Metabase contents using standardized metabase:// uniform resource identifiers (URIs).
• Dual Authentication Support: Accepts credentials via traditional session cookies or modern, stateless API keys.
• Standardized Output: Guarantees data delivery in easily parsable JSON format for immediate AI consumption.
• Operational Transparency: Features comprehensive, granular logging for troubleshooting and usage auditing.
• Resilient Error Reporting: Implements rigorous failure detection, yielding explicit, actionable error messages.

Exposed Tool Set

The server furnishes the following distinct functionalities for integrated AI assistants:

Data Exploration Utilities

• fetch_all_dashboards: Obtain a catalog of all accessible dashboards within the Metabase deployment.
• retrieve_saved_questions: List all pre-defined queries or 'cards' registered in Metabase.
• enumerate_data_sources: View a registry of all interconnected source databases.
• list_content_folders: List all organizational collections housing reports and dashboards.
• describe_database_tables: List all tabular structures resident within a specified database schema.
• inspect_table_schema: Retrieve the full field (column) definitions for any given table.

Query Execution Functions

• run_saved_asset: Execute a pre-configured card, optionally supplying runtime parameters.
• execute_raw_sql: Run arbitrary SQL commands against any permitted underlying data repository.

Dashboard Administration

• extract_dashboard_layout: Determine which analytical cards constitute a specific dashboard.
• provision_new_dashboard: Instantiate a dashboard entity with provided naming and structural metadata.
• modify_dashboard_properties: Alter the designation, commentary, or configuration of an existing dashboard.
• retire_dashboard: Permanently erase a dashboard entity.
• reconfigure_dashboard_contents: Insert, reposition, or update cards associated with a dashboard, including tab placement.

Question/Card Lifecycle Management

• create_new_question: Generate a new analytical card defined by a specific SQL expression.
• reconfigure_card_view: Modify the visual presentation settings (e.g., chart type) for an existing card.

Organizational Management

• establish_new_collection: Create a fresh organizational folder for grouping reports and dashboards.

System Configuration Directives

The connectivity layer supports two primary credentialing modes:

Mode A: Email and Password Login

bash

Essential Settings

METABASE_URL=https://your-metabase-instance.com METABASE_USER_EMAIL=your_email@example.com METABASE_PASSWORD=your_secret_password

Optional Tuning

LOG_LEVEL=info # Permitted values: debug, info, warn, error, fatal

Mode B: API Key Credentialing (Recommended Production Standard)

bash

Essential Settings

METABASE_URL=https://your-metabase-instance.com METABASE_API_KEY=your_secure_api_token

Optional Tuning

LOG_LEVEL=info # Permitted values: debug, info, warn, error, fatal

Configuration is typically managed via environment variables or populated within a .env file utilizing the dotenv utility.

Deployment Strategy via Smithery

To integrate this MCP server with conversational agents like Claude, users should adopt the Smithery orchestration framework:

Deployment Protocol:

1. Create a personal fork of this source repository on GitHub.
2. Navigate to the Smithery Portal and establish authentication with your GitHub account.
3. Utilize Smithery's interface to initiate the deployment of your forked repository.

Configuration for Claude Desktop Integration

Adjust the local configuration file for seamless connectivity with the Smithery-hosted service:

MacOS Path: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows Path: %APPDATA%/Claude/claude_desktop_config.json

API Key Auth Payload Example:

{ "mcpServers": { "metabase-connector-ai": { "command": "npx", "args": [ "-y", "@smithery/cli@latest", "run", "YOUR_GITHUB_USERNAME/metabase-connector-ai", "--config", "{\"metabaseUrl\":\"https://your-metabase-instance.com\",\"metabaseApiKey\":\"your_api_key\",\"metabasePassword\":\"\",\"metabaseUserEmail\":\"\"}" ] } } }

Username/Password Auth Payload Example:

{ "mcpServers": { "metabase-connector-ai": { "command": "npx", "args": [ "-y", "@smithery/cli@latest", "run", "YOUR_GITHUB_USERNAME/metabase-connector-ai", "--config", "{\"metabaseUrl\":\"https://your-metabase-instance.com\",\"metabaseApiKey\":\"\",\"metabasePassword\":\"your_password\",\"metabaseUserEmail\":\"your_email@example.com\"}" ] } } }

Security Posture

• API key usage is strongly advised for production environments over persistent credential storage.
• Safeguard all sensitive API tokens and login credentials.
• Prioritize externalizing secrets using dedicated environment variable mechanisms.
• Implement stringent network access controls to limit exposure of the Metabase endpoint.

Development Guidelines

Contributions, feature requests, and patches are highly encouraged. Please utilize standard Pull Request workflows.