OmniSQL MCP

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

이 프로젝트는 SSH 터널 / 점프 호스트 지원을 추가한 srthkdev/omnisql-mcp의 포크입니다. npm에 게시되지 않았습니다 — 이 저장소에서 직접 빌드하세요 (설치 참조).

지원 데이터베이스

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

• PostgreSQL (pg 경유)

• MySQL / MariaDB (mysql2 경유)

• SQL Server / MSSQL (mssql 경유)

• SQLite (sqlite3 CLI 경유)

• Trino / Presto (trino-client 경유)

Postgres 호환 (pg 드라이버로 자동 라우팅):

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

기타 데이터베이스: OMNISQL_CLI_PATH로 구성된 외부 CLI로 폴백합니다. 결과는 CLI에 따라 다릅니다.

Related MCP server: DBHub

기능

• 로컬 DB 클라이언트 워크스페이스에 이미 구성된 연결을 재사용 — 중복 설정 불필요

• 자동 SSH 터널 / 점프 호스트 지원: 연결에 구성된 것과 동일한 SSH 터널 및 게이트웨이/점프 호스트 프로필(체인 점프 서버 포함)을 통해 투명하게 연결 — 별도의 터널 설정 불필요

• PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, Trino/Presto에 대한 네이티브 쿼리 실행

• 구성 가능한 풀 크기 및 타임아웃을 갖춘 연결 풀링(SQLite 및 Trino/Presto는 쿼리당 비연결 방식이므로 풀링 미적용)

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

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

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

• execute_query에서 SELECT 전용을 강제하는 읽기 전용 모드

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

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

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

• CSV/JSON 데이터 내보내기

• 연결 풀 정리를 통한 정상 종료

요구 사항

• Node.js 18+

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

설치

이 포크는 npm에 게시되지 않았습니다 — 소스에서 빌드하세요:

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

그런 다음 빌드된 서버를 링크하여 omnisql-mcp 명령이 이를 가리키도록 하세요:

npm install -g .

npm install -g omnisql-mcp을 단독으로 실행하지 마세요. 이는 SSH 터널 / 점프 호스트 지원이 없는 원본 업스트림 패키지를 npm 레지스트리에서 설치합니다. 이 저장소를 클론하고 로컬에서 빌드한 다음, 위에 표시된 대로 클론된 폴더 안에서 npm install -g .을 실행해야 합니다.

구성

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 서버에 추가:

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

전역 설치 없이

npm install -g .을 실행하고 싶지 않다면, MCP 클라이언트를 빌드된 진입점에 직접 지정하세요:

{
  "mcpServers": {
    "omnisql": {
      "command": "node",
      "args": ["/absolute/path/to/omnisql-mcp/dist/index.js"]
    }
  }
}

환경 변수

읽기 전용 모드

모든 쓰기 작업을 차단합니다. 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 - 연결 풀 통계 가져오기

SSH 터널 / 점프 호스트

• get_ssh_tunnel_info - 연결과 연결된 SSH 터널 / 점프 호스트 프로필 검사 (비밀 정보는 마스킹됨)

기타

• 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를 통해 모든 도구를 비활성화할 수 있습니다.

• 입력 검증: 연결 ID와 SQL 식별자는 주입을 방지하기 위해 검증됩니다.

• 권장 사항: 프로덕션 사용 시 심층 방어를 위해 데이터베이스 수준의 읽기 전용 사용자도 함께 사용하세요.

워크스페이스 형식 지원

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

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

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

자격 증명은 워크스페이스 credentials-config.json에서 자동으로 복호화됩니다.

SSH 터널 / 점프 호스트 지원

DB 클라이언트에서 연결에 SSH 터널(네트워크 핸들러)이 구성된 경우 — 하나 이상의 체인 점프 서버 / 게이트웨이 호스트를 포함 — 모든 네이티브 쿼리, test_connection, 트랜잭션 및 풀링된 연결이 투명하게 이를 통해 라우팅됩니다. 별도의 터널 설정은 필요 없습니다: 서버는 DB 클라이언트가 사용할 것과 동일한 SSH 홉 체인을 통해 로컬 포트 포워드를 열고 네이티브 드라이버(pg, mysql2, mssql)를 해당 로컬 엔드포인트에 연결합니다.

• 홉당 비밀번호, 공개 키 및 SSH 에이전트 인증 지원

• 체인 점프 서버 지원 (localhost -> 점프 호스트 -> 최종 SSH 호스트 -> 데이터베이스)

• 터널은 연결당 한 번 열리고 쿼리 간에 재사용되며 종료 시 닫힙니다.

• get_ssh_tunnel_info를 사용하여 비밀 정보를 노출하지 않고 연결의 터널/점프 호스트 프로필(호스트, 포트, 인증 유형, 점프 서버 수)을 검사하세요.

• 비밀번호나 키 암호문을 워크스페이스의 암호화된 자격 증명 저장소에서 복구할 수 없는 경우, 폴백으로 OMNISQL_SSH_PASSWORD, OMNISQL_SSH_PASSPHRASE 또는 OMNISQL_SSH_PRIVATE_KEY_PATH를 설정하세요.

Trino / Presto 지원

Trino 연결은 연결에 이미 저장된 동일한 호스트/사용자/비밀번호를 사용하여 HTTPS/HTTP(기본 인증)를 통해 작동합니다. Trino 관련 참고 사항 몇 가지:

• 카탈로그/스키마는 선택 사항입니다. 연결에 기본 카탈로그/스키마가 구성되지 않은 경우(DBeaver에서 여러 카탈로그를 탐색할 때 흔함), 쿼리는 테이블을 catalog.schema.table로 완전히 한정해야 합니다.

• list_tables 및 get_table_schema는 설계상 카탈로그에 구애받지 않습니다 (system.jdbc.tables/system.jdbc.columns 경유). 따라서 기본 카탈로그 없이도 작동하지만, 대규모 다중 카탈로그 클러스터에서는 모든 카탈로그의 메타데이터를 스캔하므로 느릴 수 있고, 동일한 테이블 이름이 둘 이상의 카탈로그/스키마에 존재하면 중복 행이 반환될 수 있습니다. 빠르고 명확한 조회가 필요하면 대신 execute_query와 함께 DESCRIBE catalog.schema.table을 사용하세요.

• SSH 터널링(위)은 Trino 연결에서도 다른 드라이버와 동일하게 작동합니다.

• Trino에는 이 서버에서 영구 세션/트랜잭션 모델이 없습니다 — Trino 연결에는 begin_transaction 및 연결 풀링을 사용할 수 없습니다(SQLite와 동일).

개발

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

라이선스

MIT