OmniSQL MCP

범용 데이터베이스 MCP 서버 — 로컬 DB 클라이언트 작업 공간(DBeaver 호환)에 이미 저장된 연결을 사용하여 AI 어시스턴트에게 데이터베이스에 대한 읽기/쓰기 권한을 부여합니다.

데이터베이스 지원

기본 지원 (직접 드라이버, 빠름):

• PostgreSQL (via pg)

• MySQL / MariaDB (via mysql2)

• SQL Server / MSSQL (via mssql)

• SQLite (via sqlite3 CLI)

Postgres 호환 (pg 드라이버를 통해 자동 라우팅):

• CockroachDB, TimescaleDB, Amazon Redshift, YugabyteDB, AlloyDB, Supabase, Neon, Citus

기타 데이터베이스: OMNISQL_CLI_PATH를 통해 구성된 외부 CLI로 대체됩니다. 결과는 CLI에 따라 다릅니다.

Related MCP server: MySQL MCP Server

기능

• 로컬 DB 클라이언트 작업 공간에 이미 구성된 연결 재사용 — 중복 설정 불필요

• PostgreSQL, MySQL/MariaDB, SQLite, SQL Server에 대한 기본 쿼리 실행

• 구성 가능한 풀 크기 및 타임아웃을 갖춘 연결 풀링

• 트랜잭션 지원 (BEGIN/COMMIT/ROLLBACK)

• 쿼리 실행 계획 분석 (EXPLAIN)

• 마이그레이션 스크립트 생성을 포함한 연결 간 스키마 비교

• execute_query에서 SELECT 전용으로 강제되는 읽기 전용 모드

• 액세스 가능한 데이터베이스를 제한하는 연결 화이트리스트

• 특정 작업을 비활성화하는 도구 필터링

• 위험한 작업(DROP DATABASE, TRUNCATE, WHERE 절 없는 DELETE/UPDATE)을 차단하는 쿼리 유효성 검사

• CSV/JSON으로 데이터 내보내기

• 연결 풀 정리를 포함한 정상 종료

요구 사항

• Node.js 18+

• 최소 하나 이상의 연결이 구성된 로컬 DB 클라이언트 (DBeaver 호환)

설치

npm install -g omnisql-mcp

구성

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS)에 추가:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Claude Code

~/.claude/settings.json에 추가:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Cursor

Cursor 설정 > MCP Servers에 추가:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

환경 변수

읽기 전용 모드

모든 쓰기 작업을 차단합니다. execute_query 도구는 SELECT, EXPLAIN, SHOW 및 DESCRIBE 문만 허용합니다. 트랜잭션 도구는 완전히 비활성화됩니다.

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_READ_ONLY": "true"
      }
    }
  }
}

연결 화이트리스트

표시할 작업 공간 연결을 제한합니다. 쉼표로 구분된 연결 ID 또는 표시 이름을 허용합니다:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_ALLOWED_CONNECTIONS": "dev-postgres,staging-mysql"
      }
    }
  }
}

특정 도구 비활성화

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_DISABLED_TOOLS": "drop_table,alter_table,write_query"
      }
    }
  }
}

사용 가능한 도구

연결 관리

• list_connections - 모든 데이터베이스 연결 나열

• get_connection_info - 연결 세부 정보 가져오기

• test_connection - 연결 테스트

데이터 작업

• execute_query - 읽기 전용 쿼리 실행 (SELECT, EXPLAIN, SHOW, DESCRIBE만 가능)

• write_query - INSERT/UPDATE/DELETE 실행

• export_data - CSV/JSON으로 내보내기

스키마 관리

• list_tables - 테이블 및 뷰 나열

• get_table_schema - 테이블 구조 가져오기

• create_table - 테이블 생성

• alter_table - 테이블 수정

• drop_table - 테이블 삭제 (확인 필요)

트랜잭션

• begin_transaction - 새 트랜잭션 시작

• execute_in_transaction - 트랜잭션 내에서 쿼리 실행

• commit_transaction - 트랜잭션 커밋

• rollback_transaction - 트랜잭션 롤백

쿼리 분석

• explain_query - 쿼리 실행 계획 분석

• compare_schemas - 두 연결 간의 스키마 비교

• get_pool_stats - 연결 풀 통계 가져오기

기타

• get_database_stats - 데이터베이스 통계

• append_insight - 분석 메모 저장

• list_insights - 저장된 메모 검색

보안

• 읽기 전용 강제: execute_query는 읽기 전용 문(SELECT, EXPLAIN, SHOW, DESCRIBE, PRAGMA)만 허용합니다. 쓰기 작업은 write_query를 사용해야 합니다.

• 쿼리 유효성 검사: DROP DATABASE, DROP SCHEMA, TRUNCATE, WHERE 절 없는 DELETE/UPDATE, GRANT, REVOKE 및 사용자 관리 문을 차단합니다.

• 연결 화이트리스트: OMNISQL_ALLOWED_CONNECTIONS를 통해 노출되는 연결을 제한합니다.

• 도구 필터링: OMNISQL_DISABLED_TOOLS를 통해 모든 도구를 비활성화할 수 있습니다.

• 입력 살균(Sanitization): 연결 ID와 SQL 식별자는 인젝션을 방지하기 위해 살균됩니다.

• 권장 사항: 프로덕션 환경에서는 심층 방어를 위해 데이터베이스 수준의 읽기 전용 사용자를 사용하는 것이 좋습니다.

작업 공간 형식 지원

DBeaver 호환 DB 클라이언트에서 작성된 두 가지 구성 형식을 모두 지원합니다:

• 레거시: .metadata/.plugins/org.jkiss.dbeaver.core/의 XML 구성

• 최신: General/.dbeaver/의 JSON 구성

자격 증명은 작업 공간의 credentials-config.json에서 자동으로 복호화됩니다.

개발

git clone https://github.com/srthkdev/omnisql-mcp.git
cd omnisql-mcp
npm install
npm run build
npm test
npm run lint

라이선스

MIT