MCP Container

metabase-mcp

Metabase MCPサーバーは、Metabase分析プラットフォームとのAI統合を目的とした高性能なモデルコンテキストプロトコルサーバーです。インテリジェントキャッシングや応答最適化、包括的なデータアクセスツールを提供します。デスクトップ拡張機能として利用可能で、ユーザーは簡単にインストールし、設定を行うことができます。

GitHubWebsiteDocs

GitHubスター

13

ユーザー評価

未評価

お気に入り

0

閲覧数

22

フォーク

3

イシュー

3

README
Metabase MCP Server

smithery badge

Version: 1.0.0

Author: Jericho Sequitin (@jerichosequitin)

A high-performance Model Context Protocol server for AI integration with Metabase analytics platforms. Features intelligent caching, response optimization, and comprehensive data access tools.

Available as a Desktop Extension (DXT) for Claude Desktop.

Installation Options
Option 1: Desktop Extension (Recommended for Claude Desktop Users)
  1. Download metabase-mcp.dxt from Releases
  2. Open the .dxt file with Claude Desktop to install
  3. Configure your Metabase credentials in Claude Desktop's extension settings:
    • Metabase URL (required)
    • Authentication: Choose either API key OR email/password
    • Export Directory: Customize where files are saved (defaults to Downloads/Metabase)
    • Optional: Log level, cache TTL, and request timeout settings
Benefits of DXT Installation
  • Single-click installation: No manual configuration files or command-line setup
  • Automatic updates: Claude Desktop manages extension updates
  • User-friendly settings: Configure through Claude Desktop's UI
  • Seamless integration: Tools automatically available in your conversations
Option 2: Manual Installation

Follow the standard MCP server installation process detailed in the Local Development Setup section below.

Key Features
  • High Performance: Up to 90% token reduction through response optimization
  • Unified Commands: list, retrieve, search, execute, and export tools
  • Smart Caching: Multi-layer caching with configurable TTL
  • Dual Authentication: API key or email/password authentication
  • Large Data Export: Export up to 1M rows in CSV, JSON, and XLSX formats
  • Configurable Export Directory: Customize where files are saved
Available Tools

The server exposes the following optimized tools for AI assistants:

Unified Core Tools

  • list: Fetch ALL records for a single resource type with highly optimized responses

    • Supports: cards, dashboards, tables, databases, collections
    • Returns only essential identifier fields for efficient browsing
    • Pagination support for large datasets exceeding token limits (offset/limit parameters)
    • Intelligent caching with performance metrics

  • retrieve: Get detailed information for specific items by ID

    • Supports: card, dashboard, table, database, collection, field
    • Concurrent processing with controlled batch sizes
    • Aggressive response optimization (75-90% token reduction)*
    • Table pagination for large databases exceeding 25k token limits

  • search: Unified search across all Metabase items using native search API

    • Supports all model types with advanced filtering
    • Search by name, ID, content, or database
    • Includes dashboard questions and native query search
Query Execution Tools

  • execute: Unified command for executing SQL queries or saved cards (2K row limit)

    • SQL Mode: Execute custom SQL queries with database_id and query parameters
    • Card Mode: Execute saved Metabase cards with card_id parameter and optional filtering
    • Card Parameters: Filter card results using card_parameters array with name/value pairs
    • Enhanced with proper LIMIT clause handling and parameter validation
    • Intelligent mode detection with strict parameter validation

  • export: Unified command for exporting large datasets (up to 1M rows)

    • SQL Mode: Export custom SQL query results with database_id and query parameters
    • Card Mode: Export saved Metabase card results with card_id parameter and optional filtering
    • Card Parameters: Filter card results before export using card_parameters array
    • Supports CSV, JSON, and XLSX formats with case-insensitive format handling
    • Automatic file saving to configurable directory (defaults to ~/Downloads/Metabase/)
Utility Tools
  • clear_cache: Clear internal cache with granular control
    • Supports model-specific cache clearing for both individual items and lists
    • Individual item caches: cards, dashboards, tables, databases, collections, fields
    • List caches: cards-list, dashboards-list, tables-list, databases-list, collections-list
    • Bulk operations: all, all-individual, all-lists
Quick Start Examples
// List all cards
list({ model: "cards" })

// Get detailed card information
retrieve({ model: "card", ids: [1, 2, 3] })

// Search for dashboards
search({ query: "sales", models: ["dashboard"] })

// Execute SQL query
execute({
  database_id: 1,
  query: "SELECT * FROM users LIMIT 100"
})

// Export large dataset
export({
  database_id: 1,
  query: "SELECT * FROM large_table",
  format: "csv"
})
Configuration
Authentication Options

API Key (Recommended):

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

Email/Password:

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

Optional Settings:

EXPORT_DIRECTORY=~/Downloads/Metabase  # Or ${DOWNLOADS}/Metabase
LOG_LEVEL=info
Manual Installation (Developers)
Prerequisites
  • Node.js 18.0.0 or higher
  • Active Metabase instance
Setup
# Clone and build
git clone https://github.com/jerichosequitin/metabase-mcp.git
cd metabase-mcp
npm install
npm run build
Environment Configuration

Create a .env file:

# Required
METABASE_URL=https://your-metabase-instance.com

# Choose authentication method
METABASE_API_KEY=your_api_key  # Recommended
# OR
# METABASE_USER_EMAIL=your_email@example.com
# METABASE_PASSWORD=your_password

# Optional
EXPORT_DIRECTORY=~/Downloads/Metabase  # Or ${DOWNLOADS}/Metabase
LOG_LEVEL=info
CACHE_TTL_MS=600000 # 10 minutes by default
REQUEST_TIMEOUT_MS=600000 # 10 minutes by default
Claude Desktop Integration

To integrate with Claude Desktop, you'll need to configure the MCP server in Claude's configuration file.

Configuration File Locations:
  • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%/Claude/claude_desktop_config.json
For Local Development:
{
  "mcpServers": {
    "metabase-mcp": {
      "command": "/Users/your-username/path/to/metabase-mcp/build/src/index.js",
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_api_key_here",
        "LOG_LEVEL": "info",
        "CACHE_TTL_MS": "600000",
        "EXPORT_DIRECTORY": "/path/to/your/export/directory"
      }
    }
  }
}
Important Notes:
  • Use absolute paths for local development (e.g., /Users/username/Documents/metabase-mcp/build/src/index.js)
  • Replace your-username with your actual username
  • Replace path/to/metabase-mcp with the actual path to your cloned repository
  • No need to run the server manually - Claude Desktop will automatically invoke and manage the MCP server via STDIO
  • Never commit real credentials to version control
  • Restart Claude Desktop after making configuration changes
Troubleshooting:
  • Ensure the path to build/src/index.js is correct and the file exists
  • Verify your Metabase credentials are valid
  • Check Claude Desktop's logs for any connection errors
  • Make sure the server builds successfully with npm run build
Advanced Usage
Card Parameters

For executing saved cards with filters, use the card_parameters array:

execute({
  card_id: 42,
  card_parameters: [
    {
      "id": "param-uuid",
      "slug": "start_date",
      "target": ["dimension", ["template-tag", "start_date"]],
      "type": "date/all-options",
      "value": "2024-01-01~2024-12-31"
    }
  ]
})

Get parameter structure by retrieving card details first.

Pagination
// List with pagination
list({ model: "cards", limit: 100, offset: 0 })

// Large database tables
retrieve({ model: "database", ids: [1], table_limit: 20 })
Debugging

Use the MCP Inspector for development:

npm run inspector
Docker Support
# Build and test
docker build -t metabase-mcp .
docker run -e METABASE_URL=https://metabase.example.com \
           -e METABASE_API_KEY=your_api_key \
           metabase-mcp

Note: Docker is primarily for development/testing.

Development
Testing
# Run tests
npm test

# Coverage report
npm run test:coverage

# Development tools
npm run inspector  # MCP Inspector for debugging
Building DXT Package
# Build for distribution
npm run dxt:build

Creates metabase-mcp.dxt ready for GitHub Releases.

Security Considerations
  • API Key Authentication: Recommended for production environments
  • Credential Security: Environment variable-based configuration
  • Docker Secrets: Support for Docker secrets and environment variables
  • Network Security: Apply appropriate network security measures
  • Rate Limiting: Built-in request rate limiting and timeout handling
License

This project is licensed under the MIT License.

作者情報
Jericho Sequitin
Jericho Sequitin
@IndependentIPManila
GitHub

10

フォロワー

2

リポジトリ

0

Gist

0

貢献数

関連するMCP
n8n logo
n8n
135889

n8nは、ノーコードでワークフローを自動化するためのオープンソースツールです。多様なアプリケーションやサービスを連携させ、データの流れを簡単に管理できます。直感的なインターフェースを持ち、ユーザーは複雑なプロセスを視覚的に構築できます。

TypeScript
typescript-sdk logo
typescript-sdk
9630

The official TypeScript SDK for Model Context Protocol servers and clients

TypeScript
mcp-playwright logo
mcp-playwright
4716

mcp-playwrightは、Playwrightを用いた自動化テストのためのMCPサーバーです。開発者が効率的にテストを実行できるように設計されており、セキュリティ評価も受けています。使いやすさと拡張性を兼ね備えたツールです。

TypeScript