데이터베이스용 MCP 도구 상자, Gemini CLI 및 기타 에이전트와 함께 Spanner 사용

이 문서에서는 Spanner 인스턴스를 모델 컨텍스트 프로토콜 (MCP)을 지원하는 다양한 개발자 도구에 연결하는 방법을 설명합니다.

Gemini CLI 전용 Spanner 확장 프로그램을 사용하는 것이 좋습니다. 이 확장 프로그램은 별도의 서버 연결을 설정할 필요성을 추상화합니다. Gemini CLI를 사용하도록 Gemini Code Assist를 구성하여 IDE에서 유사한 설정 이점을 누릴 수 있습니다. 자세한 내용은 Gemini CLI 확장 프로그램 - Spanner를 참고하세요.

또는 MCP를 지원하는 다른 IDE와 개발자 도구를 데이터베이스용 MCP 도구 상자를 통해 연결할 수 있습니다. MCP Toolbox는 AI 에이전트를 데이터에 연결하도록 설계된 오픈소스 MCP 서버입니다. 인증 및 연결 풀링과 같은 작업을 처리하므로 IDE에서 직접 자연어로 데이터와 상호작용할 수 있습니다.

Spanner에서 Gemini CLI 확장 프로그램 사용

참고: 데이터베이스용 MCP 도구 상자는 베타 (v1.0 이전)이며 첫 번째 안정화 버전이 출시될 때까지 브레이킹 체인지가 발생할 수 있습니다. (v1.0)

Gemini CLI와의 Spanner 통합은 표준 MCP Toolbox 연결에 비해 추가 기능을 제공하는 오픈소스 확장 프로그램을 통해 이루어집니다. 이 확장 프로그램은 설치, 구성, 사용 예시에 관한 자세한 정보를 제공할 뿐만 아니라 설치 프로세스와 도구 모음을 제공합니다. Gemini CLI 확장 프로그램을 사용하는 경우 MCP Toolbox를 설치할 필요가 없습니다. 자세한 내용은 Gemini CLI 확장 프로그램 - Spanner를 참고하세요.

spanner 확장 프로그램에는 테이블을 나열하고 SQL 및 SQL DQL 문을 실행하는 도구가 포함되어 있습니다.

도구	자연어 프롬프트 예시
list_tables	내 Spanner 인스턴스에는 어떤 테이블이 있나요?
execute_sql	제품 테이블에 테스트 데이터를 삽입합니다.
execute_sql_dql	미국에서 판매되는 전자제품 카테고리의 제품은 무엇인가요?

시작하기 전에

1. Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.

2. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

Spanner 인스턴스 설정

1. Google Cloud 프로젝트에서 Spanner API 사용 설정

2. Spanner 인스턴스와 데이터베이스 만들기 또는 선택

3. 이 태스크를 완료하는 데 필요한 역할과 권한을 구성합니다. LLM 에이전트를 호출하는 사용자에게는 데이터베이스 수준에서 다음 역할이 필요합니다.

   • DQL 쿼리를 실행하고 테이블을 나열하는 Cloud Spanner 데이터베이스 리더 (roles/spanner.databaseReader)

   • DML 쿼리를 실행하는 Cloud Spanner 데이터베이스 사용자 (roles/spanner.databaseUser)

4. 환경에 애플리케이션 기본 사용자 인증 정보(ADC)를 구성합니다.

MCP Toolbox 설치

참고: MCP Toolbox는 Gemini CLI 또는 Gemini Code Assist 이외의 MCP 클라이언트에만 필요합니다. Gemini CLI 또는 Gemini Code Assist를 사용하는 경우 이 섹션을 건너뛰세요.

1. MCP Toolbox의 최신 버전을 바이너리로 다운로드합니다. 운영체제(OS) 및 CPU 아키텍처에 해당하는 바이너리를 선택합니다. MCP Toolbox 버전 0.15.0 이상을 사용해야 합니다.

   linux/amd64

   curl -O https://storage.googleapis.com/genai-toolbox/version/linux/amd64/toolbox
   
   

   darwin/arm64

   curl -O https://storage.googleapis.com/genai-toolbox/version/darwin/arm64/toolbox
   
   

   darwin/amd64

   curl -O https://storage.googleapis.com/genai-toolbox/version/darwin/amd64/toolbox
   
   

   windows/amd64

   curl -O https://storage.googleapis.com/genai-toolbox/version/windows/amd64/toolbox
   
   

2. 바이너리를 실행 가능하게 만듭니다.

   chmod +x toolbox
   

3. 설치를 확인합니다.

   ./toolbox --version
   

에이전트 도구 설정

이 섹션에서는 Spanner 인스턴스에 연결하도록 다양한 개발자 도구를 구성하는 방법을 설명합니다. 다음 옵션 중에서 에이전트 도구를 선택합니다.

Gemini CLI

1. Gemini CLI를 설치합니다.
   
2. 다음 명령어를 사용하여 GitHub 저장소에서 Gemini CLI용 Spanner 확장 프로그램을 설치합니다.
   

  gemini extensions install https://github.com/gemini-cli-extensions/spanner
  

3. Spanner 인스턴스에 연결하려면 다음 환경 변수를 설정하세요.
   

       export SPANNER_PROJECT: "PROJECT_ID"
       export SPANNER_INSTANCE: "INSTANCE_NAME"
       export SPANNER_DATABASE: "DATABASE_NAME"
       export SPANNER_DIALECT: "DIALECT_NAME"
       

   다음을 바꿉니다.
   • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
   • INSTANCE_NAME: Spanner 인스턴스 이름
   • DATABASE_NAME: Spanner 데이터베이스 이름
   • DIALECT_NAME: Spanner SQL 언어입니다. googlesql 또는 postgresql를 허용합니다. 정의되지 않은 경우 기본값은 googlesql입니다.
4. 대화형 모드에서 Gemini CLI를 시작합니다.

       gemini
       

   CLI는 Gemini CLI 및 해당 도구의 Spanner 확장 프로그램을 자동으로 로드하며, 이를 사용하여 데이터베이스와 상호작용할 수 있습니다.

Gemini Code Assist

이 접근 방식을 사용하면 MCP 서버를 수동으로 구성할 필요가 없으므로 Gemini CLI를 사용하도록 Gemini Code Assist를 구성하는 것이 좋습니다. 하지만 MCP 서버를 수동으로 구성하는 방법은 다음 섹션에서 확인할 수 있습니다.

1. VS Code에 Gemini Code Assist 확장 프로그램을 설치합니다.
2. 에이전트 모드를 사용 설정하고 에이전트 모델을 Gemini로 전환합니다.
3. 프로젝트 루트 디렉터리에 .gemini라는 폴더를 만들고 그 안에 settings.json 파일을 만듭니다.
4. settings.json 파일에서 Spanner 언어에 따라 다음 구성 중 하나를 추가합니다.
5. 다음 변수를 값으로 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID입니다.
• INSTANCE_NAME: Spanner 인스턴스 이름
• DATABASE_NAME: Spanner 데이터베이스 이름

6. 파일을 저장합니다.

GoogleSQL 언어를 사용하는 Spanner:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

PostgreSQL 언어를 사용하는 Spanner:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Claude Code

1. Claude Code를 설치합니다.
2. 프로젝트 루트에 .mcp.json 파일이 없으면 만듭니다.
3. Spanner 언어에 따라 다음 구성 중 하나를 추가하고, 환경 변수를 값으로 대체하고, 파일을 저장합니다.

GoogleSQL 언어를 사용하는 Spanner:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

PostgreSQL 언어를 사용하는 Spanner:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Claude for Desktop

1. Claude for Desktop을 열고 설정으로 이동합니다.
2. 개발자 탭에서 구성 수정을 클릭하여 구성 파일을 엽니다.
3. Spanner 언어에 따라 다음 구성 중 하나를 추가하고, 환경 변수를 값으로 대체하고, 파일을 저장합니다.

GoogleSQL 언어를 사용하는 Spanner:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

PostgreSQL 언어를 사용하는 Spanner:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

4. Claude for Desktop을 다시 시작합니다.
5. 새 채팅 화면에 새 MCP 서버와 함께 망치(MCP) 아이콘이 표시됩니다.

Cline

1. VS Code에서 Cline 확장 프로그램을 열고 MCP Servers 아이콘을 클릭합니다.
2. MCP 서버 구성을 탭하여 구성 파일을 엽니다.
3. Spanner 언어에 따라 다음 구성 중 하나를 추가하고, 환경 변수를 값으로 대체하고, 파일을 저장합니다.

GoogleSQL 언어를 사용하는 Spanner:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

PostgreSQL 언어를 사용하는 Spanner:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

서버가 성공적으로 연결되면 녹색 활성 상태가 표시됩니다.

Cursor

1. 프로젝트 루트에 .cursor 디렉터리가 없으면 만듭니다.
2. .cursor/mcp.json 파일이 없으면 만들고 엽니다.
3. Spanner 언어에 따라 다음 구성 중 하나를 추가하고, 환경 변수를 값으로 대체하고, 파일을 저장합니다.

GoogleSQL 언어를 사용하는 Spanner:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

PostgreSQL 언어를 사용하는 Spanner:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

4. 커서를 열고 설정 > 커서 설정 > MCP로 이동합니다. 서버가 연결되면 녹색 활성 상태가 표시됩니다.

Visual Studio Code(Copilot)

1. VS Code를 열고 프로젝트 루트에 .vscode 디렉터리가 없으면 만듭니다.
2. .vscode/mcp.json 파일이 없으면 만들고 엽니다.
3. Spanner 언어에 따라 다음 구성 중 하나를 추가하고, 환경 변수를 값으로 대체하고, 파일을 저장합니다.

GoogleSQL 언어를 사용하는 Spanner:

{
  "servers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
        "SPANNER_PROJECT": "PROJECT_ID",
        "SPANNER_INSTANCE": "INSTANCE_NAME",
        "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

PostgreSQL 언어를 사용하는 Spanner:

{
  "servers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
        "SPANNER_PROJECT": "PROJECT_ID",
        "SPANNER_INSTANCE": "INSTANCE_NAME",
        "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

Windsurf

1. Windsurf를 열고 Cascade 어시스턴트로 이동합니다.
2. MCP 아이콘을 클릭한 다음 구성을 클릭하여 구성 파일을 엽니다.
3. Spanner 언어에 따라 다음 구성 중 하나를 추가하고, 환경 변수를 값으로 대체하고, 파일을 저장합니다.

GoogleSQL 언어를 사용하는 Spanner:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}

PostgreSQL 언어를 사용하는 Spanner:

{
  "mcpServers": {
    "spanner": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","spanner-postgres","--stdio"],
      "env": {
          "SPANNER_PROJECT": "PROJECT_ID",
          "SPANNER_INSTANCE": "INSTANCE_NAME",
          "SPANNER_DATABASE": "DATABASE_NAME"
      }
    }
  }
}