sqlite-readonly-mcp

원격 Linux에서 실행되는 읽기 전용 SQLite Model Context Protocol 서비스입니다. Streamable HTTP(/mcp)를 사용하며, Bearer Token으로 인증하고 쿼리 결과는 JSON 텍스트로 반환합니다. Nginx(HTTPS) 뒤에 배치되도록 설계되었으며, 업스트림은 로컬 호스트만 수신합니다.

기능

• sqlite_query 도구: 단일 SELECT / WITH / EXPLAIN 문을 실행하고 { rows, rowCount } 형태의 JSON을 반환합니다.

• list_tables 도구: 시스템 테이블을 제외한 테이블 이름을 나열합니다.

• SQLite: better-sqlite3 readonly + fileMustExist 사용; 애플리케이션 계층에서 단일 문장 및 쿼리 접두사 제한.

• GET /health: 루프백 전용, 상태 확인용( src/server.ts 참조).

• 전송: Streamable HTTP(/mcp) + 레거시 SSE(GET /sse, POST /messages), Cursor가 필요할 때 대비.

Related MCP server: PostgreSQL MCP Server

환경 변수

로컬 빌드 및 실행

npm install
npm run build
export SQLITE_PATH=/path/to/db.sqlite
export BEARER_TOKEN='your-secret-token'
export ALLOWED_HOSTS='127.0.0.1,localhost'
node dist/server.js

개발 및 디버깅: npm run dev

Nginx 및 systemd

deploy/nginx.example.conf, deploy/sqlite-readonly-mcp.service, deploy/sqlite-readonly-mcp.env.example을 참조하세요.

핵심 사항: 업스트림으로 Authorization, Accept, Content-Type, mcp-session-id를 전달하고, SSE/청크 응답에 대해 proxy_buffering을 끕니다. 예제에는 **Streamable HTTP의 /mcp**와 함께 SSE(**/sse**, **/messages**) 역방향 프록시 설정이 포함되어 있습니다.

root 사용자로 실행 (권장 예제)

SQLite 파일 및 상위 디렉토리의 읽기 권한 설정을 간소화하기 위해, 예제에서는 root로 서비스를 시작합니다(systemd 유닛에서 User= / Group=을 설정하지 않으면 기본적으로 root로 실행됨).

1. 코드와 빌드 결과물을 /opt/sqlite-readonly-mcp 등에 배치하고 npm ci --omit=dev 및 npm run build를 실행합니다.

2. 환경 파일을 복사하고 변수를 입력합니다:

 sudo cp deploy/sqlite-readonly-mcp.env.example /etc/sqlite-readonly-mcp.env
 sudo chmod 600 /etc/sqlite-readonly-mcp.env

3. 유닛을 설치하고 활성화합니다(WorkingDirectory 및 ExecStart의 node 절대 경로를 필요에 따라 수정):

 sudo cp deploy/sqlite-readonly-mcp.service /etc/systemd/system/
 sudo systemctl daemon-reload
 sudo systemctl enable --now sqlite-readonly-mcp
 sudo systemctl status sqlite-readonly-mcp

만약 User=mcp를 직접 추가했다면, 해당 줄을 삭제한 후 daemon-reload 및 restart를 수행하세요.

보안 주의: root 프로세스가 침해될 경우 영향이 크므로, 반드시 HTTPS, Bearer, 로컬 수신 + Nginx, 방화벽을 함께 사용하세요. 최소 권한이 필요한 경우 전용 사용자로 되돌리고 데이터 파일 및 경로 권한을 별도로 구성하십시오.

수동 검증 (curl)

MCP는 클라이언트가 application/json과 text/event-stream을 모두 수락할 것을 요구합니다:

curl -sS -D - \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}' \
  "https://mcp.example.com/mcp"

잘못된 토큰은 401을 반환해야 합니다.

Cursor 클라이언트

Cursor의 MCP 설정에서 해당 원격 서비스에 대한 HTTPS URL(예: https://mcp.example.com/mcp)을 구성합니다. Bearer 토큰이 필요한 경우, 현재 Cursor 버전이 원격 MCP에 대해 사용자 지정 헤더를 지원하는지 확인하십시오. 지원하지 않는 경우, 고정된 Authorization 헤더를 추가하는 게이트웨이를 로컬에 구성해야 합니다(솔루션 위험 설명 참조).

운영

자세한 내용은 docs/RUNBOOK.md를 참조하세요.

라이선스

MIT (@modelcontextprotocol/sdk와 동일; 각 의존성 라이선스의 라이선스 준수).