SQLPad MCP Server

SQLPad용 MCP 서버입니다. AI 에이전트를 SQLPad 인스턴스에 기본 URL과 서비스 토큰으로 연결하면, 에이전트가 연결을 검색하고, 스키마를 검사하고, SQL을 실행하고, 저장된 쿼리를 관리할 수 있습니다.

요구 사항

• Node.js 20 이상.

• 접근 가능한 SQLPad 인스턴스.

• SQLPad 서버에 SQLPAD_SERVICE_TOKEN_SECRET이 구성되어 있어야 합니다. 없으면 모든 Bearer 인증 요청이 401 Unauthorized를 반환합니다.

• SQLPad 관리자 GUI에서 생성된 서비스 토큰.

Related MCP server: SQLite Database MCP Server

빠른 시작

설치 단계가 필요 없습니다 — npm에서 바로 실행하세요:

SQLPAD_SERVICE_TOKEN=... npx sqlpad-mcp --base-url https://sqlpad.example.com

또는 전역으로 설치하세요:

npm install -g sqlpad-mcp

서버는 stdio를 통해 MCP를 사용하므로, 보통 MCP 클라이언트에 의해 실행되며 수동으로 실행되지 않습니다. 직접 실행하는 것은 자격 증명을 확인하는 데 여전히 유용합니다: 성공 시 감지된 SQLPad 버전을 stderr에 기록합니다.

구성

CLI 플래그가 해당 환경 변수보다 우선합니다. 배치 폴링 간격(250ms)은 내부적이며 구성할 수 없습니다.

Claude Code 구성

Claude Code mcp.json에 서버를 추가하세요:

{
  "mcpServers": {
    "sqlpad": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "sqlpad-mcp",
        "--base-url",
        "https://sqlpad.example.com"
      ],
      "env": {
        "SQLPAD_SERVICE_TOKEN": "..."
      }
    }
  }
}

env를 통해 토큰을 제공하면 프로세스 인자 목록에서 토큰이 제외되며, 이 목록은 ps를 통해 모든 사용자가 읽을 수 있습니다.

게이트된 도구 그룹을 활성화하려면 동일한 env 블록에 "SQLPAD_ALLOW_WRITES": "true" 또는 "SQLPAD_ALLOW_ADMIN": "true"를 추가하세요.

도구

12개의 도구가 항상 등록됩니다. 6개는 두 SQLPAD_ALLOW_* 플래그 뒤에 게이트되어 기본적으로 꺼져 있습니다.

실행

검색

저장된 쿼리

저장된 쿼리 쓰기 — SQLPAD_ALLOW_WRITES=true 필요

관리자 — SQLPAD_ALLOW_ADMIN=true 필요

이들은 자체적으로 관리자 서비스 토큰이 필요한 SQLPad 엔드포인트를 호출합니다.

SQL 실행 방식

SQLPad는 비동기 배치를 통해 SQL을 실행합니다. 배치 생성은 즉시 반환됩니다. 각 문은 queued에서 started로 이동한 다음 finished 또는 error로 이동합니다. 결과는 각 문에 대해 별도로 가져오며 해당 문이 완료될 때까지 사용할 수 없습니다.

run_sql 도구는 전체 프로토콜(생성, 폴링, 가져오기, 행 반환)을 흡수하므로 에이전트는 한 번의 호출만 하면 됩니다. 폴링이 구성된 시간 초과에 도달하면 도구는 에이전트가 멈추는 대신 재개할 수 있는 batchId를 반환합니다.

연결에는 기본 데이터베이스가 없을 수 있습니다. 테이블 이름을 schema.table로 한정하고, get_connection_schema를 사용하여 사용 가능한 스키마를 검색하세요.

보안

• run_sql은 DDL 및 DML을 포함한 임의의 SQL을 실행하며 샌드박스 처리되지 않습니다. SQLPAD_ALLOW_WRITES는 SQLPad 자체의 저장된 쿼리 객체의 변경만 게이트합니다. SQL 내용을 제한하지 않습니다. SQLPad 연결 자체에서 읽기 전용 데이터베이스 자격 증명을 사용하세요. 그것이 유일한 실제 강제 수단입니다.

• SQLPad의 /api/service-tokens 엔드포인트는 의도적으로 노출되지 않습니다. 자격 증명을 발급하는 도구는 권한 상승 프리미티브입니다.

• 관리자 도구는 기본적으로 꺼져 있습니다.

• 서비스 토큰은 모든 오류와 로그에서 삭제됩니다. 모든 로깅은 stderr로 이동합니다. stdout은 JSON-RPC 채널이기 때문입니다.

• 배치는 토큰 자체의 사용자로 범위가 지정되므로 서버는 자체 쿼리 기록만 볼 수 있습니다.

기여

저장소를 클론하고 종속성을 설치하세요:

git clone https://github.com/VAIBHAV7500/sqlpad-mcp.git
cd sqlpad-mcp
npm install
npm run build

변경 사항에 대한 브랜치를 만드세요. 풀 리퀘스트를 열기 전에 다음을 실행하세요:

npm run typecheck && npm run lint && npm test

CI는 Node 20 및 22에서 동일한 세 가지 명령을 실행합니다.

라이선스

MIT