mcp-turso-cloud

mcp-turso-cloud

LLM 向けに Turso データベースとの連携を提供する Model Context Protocol（MCP）サーバーです。このサーバーは、組織レベルとデータベースレベルの両方の操作に対応する2段階認証システムを実装しており、LLM から Turso データベースを直接簡単に管理およびクエリできます。

機能

🏢 組織レベルの操作

• データベースの一覧表示：Turso 組織内のすべてのデータベースを表示します
• データベースの作成：カスタマイズ可能なオプションを指定して新しいデータベースを作成します
• データベースの削除：組織からデータベースを削除します
• データベーストークンの生成：特定のデータベース用の認証トークンを作成します

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

• テーブルの一覧表示：特定のデータベース内のすべてのテーブルを表示します
• 読み取り専用クエリの実行：SELECT および PRAGMA クエリを実行します（読み取り専用操作）
• クエリの実行：破壊的な可能性のある SQL クエリ（INSERT、UPDATE、DELETE など）を実行します
• テーブルの説明：データベーステーブルのスキーマ情報を取得します
• ベクトル検索：SQLite のベクトル拡張機能を使用してベクトル類似度検索を実行します

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

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

• SELECT、読み取り専用の WITH／VALUES、読み取りに対する EXPLAIN、および許可リストにあるメタデータ PRAGMA には、execute_read_only_query を使用します。
• INSERT、UPDATE、DELETE、CREATE、DROP、変更を伴う PRAGMA、およびデータを変更するその他の操作には、execute_query を使用します。

読み取りツールは、フルアクセスのクライアントがすでにキャッシュされている場合も含め、常に読み取り専用の Turso 認証情報を要求します。トークンエンドポイントには、クエリパラメーターとして authorization=read-only が渡されます。読み取りに失敗しても、フルアクセスにフォールバックすることはありません。トークンとクライアントは権限ごとに個別にキャッシュされ、トークンの有効期限が切れると更新されます。

ローカルの SQL 検証では、複数のステートメント、読み取りパスでの変更を伴う PRAGMA、ファイル関数／拡張機能関数を拒否します。これは保守的な振り分けチェックであり、完全な SQL パーサーでも、Turso のサーバー側認可の代わりでもありません。不明な PRAGMA 名や引用符で囲まれた PRAGMA 名には、書き込みツールが必要です。トリガー定義など、内部にセミコロンを含む複合ステートメントはサポートされていません。生成される SQL では識別子を引用符で囲み、データ値にはバインディングを使用します。

この分離により、異なる権限レベルと承認要件を適用できます。

• 多くの状況で、読み取り専用操作は自動承認できます
• 安全性を確保するため、破壊的な操作には明示的な承認を必須にできます

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

2段階認証システム

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

1. 組織レベルの認証

   • Turso Platform API トークンを使用します
   • データベースと組織レベルの操作を管理します
   • Turso ダッシュボードから取得します

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

   • データベース固有のトークンを使用します
   • 組織トークンを使って自動的に生成されます
   • パフォーマンス向上のためにキャッシュされ、必要に応じてローテーションされます

設定

このサーバーは、MCP クライアントを通じて設定する必要があります。環境ごとの例を以下に示します。

Cline／Claude Desktop の設定

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 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 Platform API トークン（必須）
• TURSO_ORGANIZATION：Turso の組織名（必須）
• TURSO_DEFAULT_DATABASE：データベースが指定されていない場合に使用するデフォルトのデータベース（任意）
• TOKEN_EXPIRATION：生成されるデータベーストークンの有効期限（任意、デフォルト：'7d'）
• TOKEN_PERMISSION：生成されるトークンの権限レベル（任意、デフォルト：'full-access'）

API

サーバーは、カテゴリ別に整理された MCP ツールを実装しています。

組織ツール

list_databases

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

パラメーター：

• limit（整数、任意）：結果の最大数。デフォルトは1000、最大は10000です
• offset（整数、任意）：スキップする結果の数。デフォルトは0、最大は1000000です

レスポンスには、returned_count、has_more、next_offsetを含むpaginationが含まれます。

レスポンスの例：

{
	"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"
		}
	]
}

create_database

組織内に新しいデータベースを作成します。

パラメーター：

• name（文字列、必須）：新しいデータベースの名前
• group（文字列、任意）：データベースを割り当てるグループ
• regions（文字列[]、任意）：データベースをデプロイするリージョン

例：

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

delete_database

組織からデータベースを削除します。

パラメーター：

• name（文字列、必須）：削除するデータベースの名前

例：

{
	"name": "test_db"
}

generate_database_token

特定のデータベース用の新しいトークンを生成します。有効期限はTOKEN_EXPIRATIONで設定します。返されるJWTは秘密情報です。

パラメーター：

• database（文字列、必須）：データベース名
• permission（文字列、任意）：権限レベル（'full-access'または'read-only'）

例：

{
	"database": "customer_db",
	"permission": "read-only"
}

データベースツール

データベース名は、英字、数字、アンダースコア、ハイフンのいずれかを1〜64文字使用できます。テーブル名とカラム名の識別子は、ヌルバイトを除く1〜64文字を受け付けます。句読点と引用符は安全にエスケープされます。指定したデータベースが現在のコンテキストになるのは、その操作が成功した場合のみです。

list_tables

データベース内のすべてのテーブルを、ページネーションのメタデータとともに一覧表示します。

パラメーター：

• database（文字列、任意）：データベース名（指定しない場合はコンテキストを使用します）
• limit（整数、任意）：結果の最大数。デフォルトは1000、最大は10000です
• offset（整数、任意）：スキップする結果の数。デフォルトは0、最大は1000000です

例：

{
	"database": "customer_db"
}

execute_read_only_query

データベースに対して、単一のSELECT、読み取り専用のWITH/VALUESクエリ、読み取りクエリのEXPLAIN、または許可リストに登録されたメタデータPRAGMAを実行します。

パラメーター：

• query（文字列、必須）：単一のSQL文。最大10000文字です
• params（オブジェクト、任意）：名前付きパラメーター、または"1"から始まる連続した位置指定キー。値には文字列、有限数、ブール値、またはnullを指定できます
• database（文字列、任意）：データベース名（指定しない場合はコンテキストを使用します）
• limit（整数、任意）：行数の上限。デフォルトは1000、最大は10000です
• offset（整数、任意）：スキップする行数。デフォルトは0、最大は1000000です

SELECT形式のクエリは、SQL内にすでにあるlimitを維持したまま、外側でlimit/offsetを適用する形でラップされます。メタデータPRAGMAとEXPLAINの結果は、取得後に切り出されます。ページングには、安定したORDER BYを使用してください。レスポンスにはresult.rowsが維持され、paginationメタデータが追加されます。

クエリ結果の行とカラム名には、512 KiBのJSON上限があります。行が収まらない場合は、取得するカラムを減らすか小さくしてください（たとえば、substrを使用します）。result.truncatedとtruncation_reasonに、省略された結果の説明が含まれます。行が1つも収まらない場合、next_offsetはnullです。BigIntは10進数の文字列で、blobは{ "type": "blob", "base64": "..." }形式になります。

例：

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

execute_query

データベースに対して、破壊的な可能性のある SQL クエリ（INSERT、UPDATE、DELETE、CREATE など）を実行します。

Parameters:

• query (string, required): 書き込みステートメントを 1 つ指定します。最大 10000 文字で、変更を伴う PRAGMA と WITH で始まる書き込みも含みます
• params (object, optional): 読み取りツールと同じパラメーター型です
• database (string, optional): データベース名です（指定しない場合はコンテキストが使用されます）

例：

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

書き込み結果の行（RETURNING など）は最大 1000 行、かつ同じバイト数の上限が適用されます。rowsAffected はそのまま返されます。切り詰められても書き込みは取り消されません。省略された行を取得するために、書き込みを再実行しないでください。

describe_table

テーブルのスキーマ情報を取得します。

Parameters:

• table (string, required): テーブル名
• database (string, optional): データベース名です（指定しない場合はコンテキストが使用されます）

例：

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

vector_search

SQLite のベクトル拡張機能を使用して、ベクトル類似検索を実行します。

Parameters:

• table (string, required): テーブル名
• vector_column (string, required): ベクトルを含む列
• query_vector (number[], required): 1～4096 個の有限数
• limit (integer, optional): 結果の最大数。デフォルトは 10、最大は 1000
• database (string, optional): データベース名です（指定しない場合はコンテキストが使用されます）

例：

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

開発

セットアップ

Node.js 24.15.0 以降と、package.json で固定されている pnpm 12.5.1 を使用します。.node-version で開発用ランタイムを選択します。

pnpm install
pnpm check
pnpm test

Vite+ は vite.config.ts を通じて、ビルド、フォーマット、Lint、型チェック、テストランナーを提供します。

• pnpm build — 実行可能ファイルと宣言ファイルを dist/ にバンドルします
• pnpm start — Turso の設定を使用してビルド済みサーバーを実行します
• pnpm dev — ソースの変更時に再ビルドします
• pnpm inspect — ビルド済みサーバーに対して MCP インスペクターを起動します
• pnpm check — フォーマット、Lint、型をチェックします
• pnpm check:fix — フォーマットと安全な Lint 修正を適用します
• pnpm format / pnpm format:check — フォーマットを実行、またはチェックします
• pnpm test — オフラインの SQL、権限、トークン、MCP ハンドラー、CLI のテストをビルドして実行します。Turso の認証情報や稼働中のデータベースへのアクセスは不要です。SQL 実行テストでは、分離されたインメモリの libSQL データベースを使用します。

依存関係のバージョンは pnpm-workspace.yaml のカタログに記載されています。新しいリリースは、インストールする前に少なくとも 2 日間経過している必要があります。

エディター

Zed には Oxc 拡張機能を、VS Code には **Vite Plus Extension Pack ** をインストールします。チェックイン済みの .zed/settings.json と .vscode/settings.json では、共有の vite.config.ts フォーマット設定を使用する Oxfmt が設定されています。Prettier の設定は使用されなくなりました。

公開

pnpm changeset
pnpm version
pnpm check
pnpm test
pnpm release

pnpm release は Changesets を通じてビルドと公開を行います。pnpm pack を使用すると、公開せずにローカルでパッケージを検証できます。

トラブルシューティング

API トークンの問題

認証エラーが発生した場合：

1. Turso API トークンが有効で、必要な権限を持っていることを確認します
2. 組織名が正しいことを確認します
3. トークンの有効期限が切れていないことを確認します

データベース接続の問題

データベースへの接続に問題がある場合：

1. 組織内にデータベースが存在することを確認します
2. API トークンがデータベースへのアクセス権を持っていることを確認します
3. データベース名のスペルが正しいことを確認します

コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。

ライセンス

MIT License — 詳細については LICENSE ファイルを参照してください。

謝辞

以下を基盤として構築されています：

• Model Context Protocol
• Turso Database
• libSQL