mcp-turso-cloud

LLM向けにTursoデータベースとの統合を提供するモデルコンテキストプロトコル（MCP）サーバー。このサーバーは、組織レベルとデータベースレベルの両方の操作を処理する2段階認証システムを実装しており、LLMからTursoデータベースを直接管理およびクエリすることを容易にします。

特徴

🏢 組織レベルの運用

• データベースの一覧表示: Turso 組織内のすべてのデータベースを表示します

• データベースの作成: カスタマイズ可能なオプションを使用して新しいデータベースを作成します

• データベースの削除: 組織からデータベースを削除します

• データベーストークンの生成: 特定のデータベースの認証トークンを作成する

💾 データベースレベルの操作

• テーブルの一覧表示: 特定のデータベース内のすべてのテーブルを表示します

• 読み取り専用クエリの実行: SELECT および PRAGMA クエリ (読み取り専用操作) を実行します。

• クエリの実行: 潜在的に破壊的な SQL クエリ (INSERT、UPDATE、DELETE など) を実行します。

• テーブルの説明: データベーステーブルのスキーマ情報を取得します

• ベクトル検索: SQLite ベクトル拡張機能を使用してベクトル類似性検索を実行します

Related MCP server: mcp-lancedb

⚠️ 重要: クエリ実行のセキュリティ ⚠️

このサーバーは、セキュリティを重視して、読み取り専用と破壊的なデータベース操作を分離します。

• SELECT および PRAGMA クエリにはexecute_read_only_query使用します (安全な読み取り専用操作)

• INSERT、UPDATE、DELETE、CREATE、DROP、およびデータを変更するその他の操作にはexecute_query使用します。

この分離により、異なる権限レベルと承認要件が可能になります。

• 読み取り専用操作は多くのコンテキストで自動承認できます

• 破壊的な操作には安全のための明示的な承認が必要になる場合があります

**SQLクエリを承認する前に、必ず注意深く読み、確認してください。**これは、データを変更または削除する可能性のある破壊的な操作の場合に特に重要です。各クエリの実行を許可する前に、そのクエリが何を行うのかをよく理解してください。

2段階認証システム

サーバーは高度な認証システムを実装しています。

1. 組織レベルの認証

   • Turso Platform APIトークンを使用する

   • データベースと組織レベルの運用を管理します

   • Tursoダッシュボードから取得

2. データベースレベルの認証

   • データベース固有のトークンを使用する

   • 組織トークンを使用して自動的に生成されます

   • パフォーマンスのためにキャッシュされ、必要に応じてローテーションされます

構成

このサーバーはMCPクライアント経由で設定する必要があります。以下に、様々な環境における設定例を示します。

Cline/Claude デスクトップ構成

Cline/Claude Desktop MCP 設定に以下を追加します:

{
	"mcpServers": {
		"mcp-turso-cloud": {
			"command": "npx",
			"args": ["-y", "mcp-turso-cloud"],
			"env": {
				"TURSO_API_TOKEN": "your-turso-api-token",
				"TURSO_ORGANIZATION": "your-organization-name",
				"TURSO_DEFAULT_DATABASE": "optional-default-database"
			}
		}
	}
}

WSL 構成の Claude デスクトップ

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 (文字列、オプション): 権限レベル ('full-access' または 'read-only')

例：

{
	"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 (number[], 必須): 類似検索のクエリベクトル

• 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ファイルを参照してください。

謝辞

構築されたもの:

• モデルコンテキストプロトコル

• Tursoデータベース

• libSQL