리드미: Metabase MCP Server

Metabase 통합을 위한 포괄적인 Model Context Protocol (MCP) 서버로, AI 어시스턴트에게 Metabase의 분석 플랫폼에 대한 완전한 액세스를 제공합니다.

🚀 빠른 시작

# Install and run with npx
export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key
npx @cognitionai/metabase-mcp-server

Related MCP server: Metabase MCP Server

✨ 기능

🎯 81개 이상의 도구 제공 - Metabase API 완전 지원

• 📊 대시보드 관리 (23개 도구) - 전체 CRUD 작업, 카드 관리, 공개 공유, 임베딩

• 📈 카드/질문 관리 (21개 도구) - 쿼리 실행, 매개변수 처리, 피벗 쿼리, 공개 링크

• 🗄️ 데이터베이스 관리 (13개 도구) - 연결 관리, 스키마 동기화, 쿼리 실행

• 📋 테이블 관리 (16개 도구) - 메타데이터 작업, 필드 관리, 데이터 작업

• 🔍 추가 도구 (9개 도구) - 컬렉션, 검색, 사용자, 활동 추적, 플레이그라운드 링크

📦 설치

💡 권장 사항: 최적의 호환성을 위해 Node.js 20.19.0+ 및 npm 8.0.0+

방법 1: NPX (권장)

npx @cognitionai/metabase-mcp-server

방법 2: 전역 설치

npm install -g @cognitionai/metabase-mcp-server
metabase-mcp-server

방법 3: Docker

docker run -it --rm \
  -e METABASE_URL=https://your-metabase-instance.com \
  -e METABASE_API_KEY=your_metabase_api_key \
  ghcr.io/CognitionAI/metabase-mcp-server

⚙️ 구성

환경 변수

API 키 인증 (권장):

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

사용자 이름/비밀번호 인증 (대체):

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

선택적 인수

서버는 도구 로딩을 사용자 지정할 수 있는 명령줄 인수를 지원합니다:

• --essential (기본값): 필수 도구만 로드

• --all: 사용 가능한 80개 이상의 모든 도구 로드

• --write: 쓰기/수정 도구만 로드

• --read: 읽기 전용 도구만 로드

# Using published package (recommended)
# Default behavior (essential tools only)
npx @cognitionai/metabase-mcp-server

# Load all tools
npx @cognitionai/metabase-mcp-server --all

# Load only write tools
npx @cognitionai/metabase-mcp-server --write

# Load only read-only tools
npx @cognitionai/metabase-mcp-server --read

# Using local development build
npm run build
node dist/server.js                    # Default (essential tools)
node dist/server.js --all             # All tools
node dist/server.js --write           # Write tools only
node dist/server.js --read            # Read-only tools only

🔌 통합 예시

Claude Desktop

Claude Desktop 구성에 추가하세요 (macOS의 ~/Library/Application Support/Claude/claude_desktop_config.json):

게시된 패키지 사용:

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

로컬 개발 빌드 사용:

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

사용자 지정 플래그 사용:

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

Windsurf IDE

Windsurf MCP 구성에 추가하세요 (~/.windsurf/mcp_config.json):

게시된 패키지 사용:

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

로컬 개발 빌드 사용:

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

사용자 지정 플래그 사용:

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

🛠️ 사용 가능한 도구

핵심 작업

• list_dashboards - 모든 대시보드 나열

• get_dashboard - ID로 대시보드 조회

• create_dashboard - 새 대시보드 생성

• update_dashboard - 기존 대시보드 업데이트

• delete_dashboard - 대시보드 삭제

• copy_dashboard - 대시보드 복사

카드 관리

• get_dashboard_cards - 대시보드의 모든 카드 조회

• add_card_to_dashboard - 대시보드에 카드 추가

• remove_card_from_dashboard - 대시보드에서 카드 제거

• update_dashboard_card - 카드 위치/설정 업데이트

• execute_dashboard_card - 특정 대시보드 카드 실행

공개 공유 및 임베딩

• create_public_link - 공개 대시보드 링크 생성

• delete_public_link - 공개 대시보드 링크 삭제

• list_public_dashboards - 공개 대시보드 목록 조회

• list_embeddable_dashboards - 임베딩 가능한 대시보드 목록 조회

매개변수 및 쿼리

• get_dashboard_param_values - 매개변수 값 가져오기

• search_dashboard_param_values - 매개변수 값 검색

• get_dashboard_param_remapping - 매개변수 리매핑 가져오기

• execute_dashboard_query - 대시보드 쿼리 실행

고급 기능

• get_dashboard_related - 관련 콘텐츠 가져오기

• get_dashboard_query_metadata - 쿼리 메타데이터 가져오기

• update_dashboard_cards - 카드 일괄 업데이트

• save_dashboard - 대시보드 변경 사항 저장

• get_dashboard_items - 대시보드 항목 가져오기

핵심 작업

• list_cards - 모든 카드/질문 나열

• get_card - ID로 카드 조회

• create_card - 새 카드 생성

• update_card - 기존 카드 업데이트

• delete_card - 카드 삭제

• copy_card - 카드 복사

쿼리 실행

• execute_card - 카드 쿼리 실행

• execute_card_query_with_format - 특정 형식으로 실행

• execute_pivot_card_query - 피벗 쿼리 실행

• get_card_query_metadata - 쿼리 메타데이터 가져오기

카드 관리

• move_cards - 컬렉션 간 카드 이동

• move_cards_to_collection - 컬렉션으로 일괄 이동

• get_card_dashboards - 카드가 포함된 대시보드 가져오기

• get_card_series - 카드 시리즈 데이터 가져오기

매개변수 및 값

• get_card_param_values - 매개변수 값 가져오기

• search_card_param_values - 매개변수 값 검색

• get_card_param_remapping - 매개변수 리매핑 가져오기

공개 공유

• create_card_public_link - 공개 카드 링크 생성

• delete_card_public_link - 공개 카드 링크 삭제

• get_public_cards - 공개 카드 목록 조회

• get_embeddable_cards - 임베딩 가능한 카드 목록 조회

핵심 작업

• list_databases - 모든 데이터베이스 나열

• get_database - 데이터베이스 세부 정보 가져오기

• create_database - 데이터베이스 연결 생성

• update_database - 데이터베이스 설정 업데이트

• delete_database - 데이터베이스 연결 삭제

스키마 및 메타데이터

• get_database_schema_tables - 데이터베이스 테이블 가져오기

• get_database_schemas - 데이터베이스 스키마 가져오기

• get_database_metadata - 전체 메타데이터 가져오기

• sync_database_schema - 스키마 메타데이터 동기화

쿼리 작업

• execute_query - SQL 쿼리 실행

• execute_query_export - 쿼리 실행 및 결과 내보내기

유지 관리

• get_database_usage_info - 사용 통계 가져오기

• rescan_database_field_values - 필드 값 다시 스캔

핵심 작업

• list_tables - 필터링하여 테이블 나열

• get_table - 테이블 세부 정보 가져오기

• update_table - 테이블 구성 업데이트

• update_tables - 테이블 일괄 업데이트

데이터 작업

• get_table_data - 테이블 데이터 가져오기

• append_csv_to_table - CSV 데이터 추가

• replace_table_csv - CSV 데이터로 교체

스키마 및 관계

• get_table_query_metadata - 쿼리 메타데이터 가져오기

• get_table_fks - 외래 키 관계 가져오기

• get_table_related - 관련 테이블 가져오기

• sync_table_schema - 테이블 스키마 동기화

필드 관리

• reorder_table_fields - 필드 표시 순서 변경

• rescan_table_field_values - 필드 값 다시 스캔

• discard_table_field_values - 캐시된 값 폐기

카드 통합

• get_card_table_fks - 카드 테이블 외래 키 가져오기

• get_card_table_query_metadata - 카드 테이블 메타데이터 가져오기

컬렉션

• list_collections - 모든 컬렉션 나열

• create_collection - 새 컬렉션 생성

• update_collection - 컬렉션 업데이트

• delete_collection - 컬렉션 삭제

• get_collection_items - 컬렉션 항목 가져오기

검색 및 탐색

• search_content - 전체 콘텐츠 검색

활동 및 분석

• get_recent_views - 최근 활동 가져오기

• get_popular_items - 인기 콘텐츠 가져오기

플레이그라운드 링크

• get_metabase_playground_link - 대화형 플레이그라운드 링크 생성

🧪 개발

설정

git clone https://github.com/CognitionAI/metabase-mcp-server.git
cd metabase-mcp-server
npm install

빌드

npm run build

개발 모드

npm run watch

디버깅

디버깅에는 MCP Inspector를 사용하세요:

npm run inspector

🔍 인증 테스트

API 키 인증

1. METABASE_URL 및 METABASE_API_KEY 설정

2. 서버를 시작하고 로그에서 "Using Metabase API Key" 확인

3. list_dashboards 도구로 테스트

사용자 이름/비밀번호 인증

1. METABASE_API_KEY 설정 해제

2. METABASE_URL, METABASE_USERNAME, METABASE_PASSWORD 설정

3. 서버를 시작하고 로그에서 "Using username/password" 확인

4. list_dashboards 도구로 테스트

🐛 문제 해결

일반적인 문제

인증 오류:

• Metabase URL에 접근 가능한지 확인

• Metabase 관리자 설정에서 API 키 유효성 확인

• 사용자 이름/비밀번호 자격 증명이 올바른지 확인

연결 문제:

• Metabase 인스턴스가 실행 중인지 확인

• 네트워크 연결 상태 확인

• HTTPS 사용 시 SSL 인증서 확인

도구 실행 오류:

• 사용자/API 키에 대한 Metabase 권한 확인

• 요청한 리소스가 존재하는지 확인

• 자세한 오류 메시지는 서버 로그 검토

📄 라이선스

이 프로젝트는 MIT 라이선스로 제공됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

🤝 기여

기여를 환영합니다! GitHub 저장소를 방문하여 다음을 할 수 있습니다:

• 🐛 버그 신고

• 💡 기능 요청

• 🔧 풀 리퀘스트 제출

• 📖 문서 개선

개발 지침

1. 저장소를 포크하세요

2. 기능 브랜치를 생성하세요

3. 테스트와 함께 변경 사항을 작성하세요

4. 모든 테스트가 통과하는지 확인하세요

5. 풀 리퀘스트를 제출하세요

🆘 지원

• 📚 문서

• 🐛 이슈 트래커

전 세계를 위해 ❤️로 만들어졌습니다