mcp-turso-cloud

LLM을 위한 Turso 데이터베이스와의 통합을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 조직 수준 및 데이터베이스 수준 작업을 모두 처리하는 2단계 인증 시스템을 구현하여 LLM에서 직접 Turso 데이터베이스를 쉽게 관리하고 쿼리할 수 있도록 합니다.

특징

🏢 조직 수준 운영

• 데이터베이스 목록 : Turso 조직의 모든 데이터베이스를 확인하세요.

• 데이터베이스 생성 : 사용자 정의 가능한 옵션으로 새 데이터베이스를 생성합니다.

• 데이터베이스 삭제 : 조직에서 데이터베이스를 제거합니다.

• 데이터베이스 토큰 생성 : 특정 데이터베이스에 대한 인증 토큰을 생성합니다.

💾 데이터베이스 수준 작업

• 테이블 목록 : 특정 데이터베이스의 모든 테이블 보기

• 읽기 전용 쿼리 실행 : SELECT 및 PRAGMA 쿼리(읽기 전용 작업)를 실행합니다.

• 쿼리 실행 : 잠재적으로 파괴적인 SQL 쿼리(INSERT, UPDATE, DELETE 등)를 실행합니다.

• 테이블 설명 : 데이터베이스 테이블에 대한 스키마 정보 가져오기

• 벡터 검색 : SQLite 벡터 확장을 사용하여 벡터 유사성 검색을 수행합니다.

Related MCP server: Supabase MCP Server

⚠️ 중요: 쿼리 실행 보안 ⚠️

이 서버는 읽기 전용 데이터베이스 작업과 파괴적 데이터베이스 작업 간에 보안 중심 분리를 구현합니다.

• SELECT 및 PRAGMA 쿼리(안전하고 읽기 전용 작업)에 대해 execute_read_only_query 사용합니다.

• 데이터를 수정하는 INSERT, UPDATE, DELETE, CREATE, DROP 및 기타 작업에 대해 execute_query 사용하세요.

이러한 분리를 통해 다양한 권한 수준과 승인 요구 사항이 허용됩니다.

• 읽기 전용 작업은 여러 컨텍스트에서 자동 승인될 수 있습니다.

• 파괴적인 작업에는 안전을 위한 명시적인 승인이 필요할 수 있습니다.

SQL 쿼리를 승인하기 전에 항상 주의 깊게 읽고 검토하세요! 이는 특히 데이터를 수정하거나 삭제할 수 있는 파괴적인 작업의 경우 매우 중요합니다. 각 쿼리가 어떤 작업을 하는지 충분히 이해한 후 실행을 허용하세요.

2단계 인증 시스템

서버는 정교한 인증 시스템을 구현합니다.

1. 조직 수준 인증

   • Turso 플랫폼 API 토큰을 사용합니다.

   • 데이터베이스와 조직 수준의 운영을 관리합니다.

   • Turso 대시보드를 통해 획득

2. 데이터베이스 수준 인증

   • 데이터베이스별 토큰을 사용합니다

   • 조직 토큰을 사용하여 자동 생성됨

   • 성능을 위해 캐시되고 필요에 따라 회전됨

구성

이 서버를 사용하려면 MCP 클라이언트를 통한 구성이 필요합니다. 다음은 다양한 환경에 대한 예시입니다.

클라인/클로드 데스크톱 구성

Cline/Claude Desktop MCP 설정에 다음을 추가하세요.

지엑스피1

WSL 구성을 사용한 Claude Desktop

WSL 환경의 경우 Claude Desktop 구성에 다음을 추가하세요.

{
	"mcpServers": {
		"mcp-turso-cloud": {
			"command": "wsl.exe",
			"args": [
				"bash",
				"-c",
				"TURSO_API_TOKEN=your-token TURSO_ORGANIZATION=your-org node /path/to/mcp-turso-cloud/dist/index.js"
			]
		}
	}
}

환경 변수

서버에는 다음과 같은 환경 변수가 필요합니다.

• TURSO_API_TOKEN : Turso 플랫폼 API 토큰(필수)

• TURSO_ORGANIZATION : Turso 조직 이름(필수)

• TURSO_DEFAULT_DATABASE : 아무것도 지정되지 않은 경우 사용할 기본 데이터베이스(선택 사항)

• TOKEN_EXPIRATION : 생성된 데이터베이스 토큰의 만료 시간(선택 사항, 기본값: '7d')

• TOKEN_PERMISSION : 생성된 토큰에 대한 권한 수준(선택 사항, 기본값: 'full-access')

API

서버는 다음과 같이 범주별로 구성된 MCP 도구를 구현합니다.

조직 도구

목록_데이터베이스

Turso 조직의 모든 데이터베이스를 나열합니다.

매개변수: 없음

응답 예시:

{
	"databases": [
		{
			"name": "customer_db",
			"id": "abc123",
			"region": "us-east",
			"created_at": "2023-01-15T12:00:00Z"
		},
		{
			"name": "product_db",
			"id": "def456",
			"region": "eu-west",
			"created_at": "2023-02-20T15:30:00Z"
		}
	]
}

데이터베이스 생성

조직 내에 새로운 데이터베이스를 만듭니다.

매개변수:

• name (문자열, 필수): 새 데이터베이스의 이름

• group (문자열, 선택 사항): 데이터베이스를 할당할 그룹

• regions (문자열[], 선택 사항): 데이터베이스를 배포할 지역

예:

{
	"name": "analytics_db",
	"group": "production",
	"regions": ["us-east", "eu-west"]
}

데이터베이스 삭제

조직의 데이터베이스를 삭제합니다.

매개변수:

• name (문자열, 필수): 삭제할 데이터베이스의 이름

예:

{
	"name": "test_db"
}

데이터베이스 토큰 생성

특정 데이터베이스에 대한 새로운 토큰을 생성합니다.

매개변수:

• database (문자열, 필수): 데이터베이스 이름

• expiration (문자열, 선택 사항): 토큰 만료 시간

• permission (문자열, 선택 사항): 권한 수준('전체 액세스' 또는 '읽기 전용')

예:

{
	"database": "customer_db",
	"expiration": "30d",
	"permission": "read-only"
}

데이터베이스 도구

리스트_테이블

데이터베이스의 모든 테이블을 나열합니다.

매개변수:

• database (문자열, 선택 사항): 데이터베이스 이름(제공되지 않으면 컨텍스트 사용)

예:

{
	"database": "customer_db"
}

읽기 전용 쿼리 실행

데이터베이스에 대해 읽기 전용 SQL 쿼리(SELECT, PRAGMA)를 실행합니다.

매개변수:

• query (문자열, 필수): 실행할 SQL 쿼리(SELECT 또는 PRAGMA여야 함)

• params (객체, 선택 사항): 쿼리 매개변수

• database (문자열, 선택 사항): 데이터베이스 이름(제공되지 않으면 컨텍스트 사용)

예:

{
	"query": "SELECT * FROM users WHERE age > ?",
	"params": { "1": 21 },
	"database": "customer_db"
}

실행_쿼리

데이터베이스에 대해 잠재적으로 파괴적인 SQL 쿼리(INSERT, UPDATE, DELETE, CREATE 등)를 실행합니다.

매개변수:

• query (문자열, 필수): 실행할 SQL 쿼리(SELECT 또는 PRAGMA일 수 없음)

• params (객체, 선택 사항): 쿼리 매개변수

• database (문자열, 선택 사항): 데이터베이스 이름(제공되지 않으면 컨텍스트 사용)

예:

{
	"query": "INSERT INTO users (name, age) VALUES (?, ?)",
	"params": { "1": "Alice", "2": 30 },
	"database": "customer_db"
}

설명_테이블

테이블에 대한 스키마 정보를 가져옵니다.

매개변수:

• table (문자열, 필수): 테이블 이름

• database (문자열, 선택 사항): 데이터베이스 이름(제공되지 않으면 컨텍스트 사용)

예:

{
	"table": "users",
	"database": "customer_db"
}

벡터 검색

SQLite 벡터 확장을 사용하여 벡터 유사성 검색을 수행합니다.

매개변수:

• table (문자열, 필수): 테이블 이름

• vector_column (문자열, 필수): 벡터를 포함하는 열

• query_vector (숫자[], 필수): 유사성 검색을 위한 쿼리 벡터

• limit (숫자, 선택 사항): 최대 결과 수(기본값: 10)

• database (문자열, 선택 사항): 데이터베이스 이름(제공되지 않으면 컨텍스트 사용)

예:

{
	"table": "embeddings",
	"vector_column": "embedding",
	"query_vector": [0.1, 0.2, 0.3, 0.4],
	"limit": 5,
	"database": "vector_db"
}

개발

설정

1. 저장소를 복제합니다

2. 종속성 설치:

npm install

3. 프로젝트를 빌드하세요:

npm run build

4. 개발 모드에서 실행:

npm run dev

출판

1. package.json의 버전 업데이트

2. 프로젝트를 빌드하세요:

npm run build

3. npm에 게시:

npm publish

문제 해결

API 토큰 문제

인증 오류가 발생하는 경우:

1. Turso API 토큰이 유효하고 필요한 권한이 있는지 확인하세요.

2. 귀하의 조직 이름이 올바른지 확인하세요

3. 토큰이 만료되지 않았는지 확인하세요

데이터베이스 연결 문제

데이터베이스에 연결하는 데 문제가 있는 경우:

1. 조직에 데이터베이스가 있는지 확인하세요

2. API 토큰이 데이터베이스에 액세스할 수 있는지 확인하세요.

3. 데이터베이스 이름이 올바르게 입력되었는지 확인하세요.

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

특허

MIT 라이센스 - 자세한 내용은 LICENSE 파일을 참조하세요.

감사의 말

기반으로 구축됨:

• 모델 컨텍스트 프로토콜

• 투르소 데이터베이스

• libSQL