Turso MCPサーバーでOAuth接続のエッジSQLiteを管理する
TursoのホストMCPサーバーをOAuthだけで接続し、組織・グループ単位のスコープ設定とブランチ機能をClaude Codeから使う手順をまとめます。
Tursoは、SQLite互換のlibSQLをベースにしたエッジデータベースで、Turso Cloud上でブランチ機能付きの管理を提供します。TursoのMCPサーバーはhttps://mcp.turso.ai/mcpにホストされた1系統だけで、認証はOAuth 2.1です。他のMCPサーバーに多い「APIキーを発行してコピーする」手順が無く、ブラウザでの同意画面を通すだけで接続できます。エージェントごとの違いはこのホストサーバーへの接続方法(パッケージング)だけで、ツール自体はどのクライアントから使っても同じです。
Tursoという名前は2つのものを指す点に注意が必要です。ひとつはオフライン・ブラウザ・デバイス上でも動く埋め込み型のデータベースエンジン、もうひとつはそのTurso/libSQLデータベースをブランチ機能付きで管理するマネージドプラットフォーム「Turso Cloud」です。このMCPサーバーが操作するのは後者、つまりTurso Cloud上の組織・データベース・グループで、埋め込みエンジン自体の挙動を直接いじるものではありません。アプリに組み込む接続コード(JavaScript・Python・Go・Rustなど各言語のドライバ)は別に用意する必要があり、MCPサーバーはあくまでクラウド側のリソース管理とSQL実行を担当します。
Claude Codeへのプラグイン導入
Claude Codeでは、Turso公式のプラグインマーケットプレイス経由で追加します。
/plugin marketplace add tursodatabase/turso-mcp
/plugin install turso@tursoインストール後、/mcpを実行してtursoを選び、Authenticateを選択するとブラウザが開きます。他のMCPサーバーのようにclaude mcp addで個別に登録する形ではなく、プラグイン経由でMCPサーバーの設定とエージェント向けスキル(skills/turso/SKILL.md、エンジン選択やドライバの使い分けを補助する)が一括で入る点が特徴です。
接続先のサーバーはhttps://mcp.turso.ai/mcpの1つだけですが、パッケージングはエージェントごとに用意されています。Codexならcodex plugin marketplace add tursodatabase/turso-mcpでプラグインを追加したあとcodex plugin add turso@tursoとcodex mcp login tursoで認証し、CursorならマーケットプレイスからTursoを検索してインストールし、Settings → MCPのログインプロンプトに従います。どのエージェントで入れても認証先とサーバーの実体は同じTursoホストなので、複数のエージェントを併用していても、組織やデータベースへのアクセス範囲は共通の同意画面で一元的に管理できます。
プラグインを使わず.mcp.jsonへ直接書くこともできます。
{
"mcpServers": {
"turso": {
"type": "http",
"url": "https://mcp.turso.ai/mcp",
"oauth": { "clientId": "turso-mcp" }
}
}
}clientIdのturso-mcpは秘匿する値ではなく、公開クライアントを識別するラベルです。安全性はクライアントID自体の秘匿ではなく、PKCEとリダイレクト先の検証、ログインのプロセスで担保されています。Claude(Claude.aiやClaude Desktop)から使う場合は、Settings → Connectors → Add custom connectorでhttps://mcp.turso.ai/mcpを指定するカスタムconnectorとして追加します。
「APIトークンを発行しなくていい」のは、Claude Codeがサーバー側から自動でエンドポイントを見つけ出す仕組みがあるからです。サーバーURLだけを渡すと、Claude CodeはWWW-Authenticateヘッダーのチャレンジを起点に、保護対象リソースのメタデータ、認可サーバーのメタデータの順に辿り、必要なエンドポイントをすべて自分で発見します(RFC 9728とRFC 8414に基づく標準的な手順)。ホスト型のクライアントであれば、ここで動的クライアント登録に対応することもできますが、Claude Codeは共有の公開クライアントID(turso-mcp)を使う実装です。
具体的な指示の例としては、次のような聞き方がそのままツール呼び出しにつながります。
- 「自分のデータベース一覧を見せて」
- 「prodグループに新しいデータベースを作って」
- 「app-dbを昨日時点のブランチとして切って」
- 「app-dbで一番遅いクエリはどれ」
- 「usersテーブルにインデックスを追加して」
組織・グループ・権限スコープを選ぶ
認証時にブラウザで開く同意画面では、エージェントに与えるアクセス範囲を選びます。
| 選択項目 | 内容 |
|---|---|
| 組織 | 内容どのTurso組織を対象にするか |
| スコープ | 内容特定のグループ1つに限定(最小権限)、または組織全体(フルアクセス) |
| 権限(グループ選択時) | 内容読み取り専用 / フルアクセス / カスタムの3種類から選択 |
グループを選ぶと、そのグループが持つリソースだけにトークンが絞られます。組織全体を選ぶとフルアクセスになりますが、どちらを選んでもトークンはTurso側のAPIで組織との紐付け・ロール・スコープを毎回チェックされ、操作は監査ログに記録されます。MCPサーバー自体は権限の判断を一切持たず、受け取ったトークンをそのままTurso Platform APIへ転送するだけの薄い層です。組織を切り替えたい、あるいはスコープを選び直したいときは、Claude Codeなら/mcp → turso → Clear authenticationで認証をクリアしてから、もう一度認証し直します。未スコープのトークンはAPI側で拒否されるため、認証をやり直さずにスコープだけ変える手段はありません。
SQL操作がツールごとに分かれている理由
Turso MCPサーバーは、SQLの実行を1つの万能ツールにまとめていません。読み取り専用クエリ、書き込み(INSERT/UPDATE)、削除、スキーマ変更(DDL)がそれぞれ別のツールとして提供されます。エージェントは実行したい操作に応じて、そのときいちばん権限の弱いツールを選べる設計です。書き込み用のツールはDELETEやDROPを実行できません。削除にはさらに専用の、名前から意図が明確なツールが分かれて存在します。読み取り専用の操作と破壊的な操作にはそれぞれ注釈が付いており、Claudeは実行前にどちらの種類かを判断し、リスクのある操作は確認を挟んでから進められます。
データベース管理とポイントインタイムブランチ
データベース関連のツールは、一覧・詳細確認・作成・削除に加えて、ブランチ作成(過去の任意時点を指定するポイントインタイムブランチを含む)とブランチ一覧、設定変更(削除保護・IP/VPCの許可リスト・サイズ上限)まで一通りをカバーします。過去のある時点の状態からブランチを切れるため、「昨日の時点のapp-dbをブランチして」のような聞き方で、特定のタイムスタンプ時点のデータベースを別ブランチとして取り出せます。
分析用途にはInsight系のツールがあり、データベースごとにクエリの頻度やレイテンシーの傾向を確認できます。「app-dbで遅いクエリはどれ」といった調査を、SQLを自分で書かずに聞けます。読み取り専用クエリのツールで実行計画を都度確認する代わりに、まずInsightで頻度・レイテンシーの傾向を俯瞰し、絞り込んだ対象だけを読み取り専用クエリで深掘りする、という順番で進めると、本番データベースに余計な負荷をかけずに調査を終えやすくなります。
データベース側の一覧・詳細確認ツールも、ブランチや設定変更と同じ「Databases」カテゴリにまとまっています。組織配下のデータベースを横断して一覧したうえで、気になった1件だけ詳細を確認し、必要ならその場でポイントインタイムブランチを切って調査用に隔離する、という流れを1つの会話の中で完結できるのが、個別にダッシュボードを開いて操作する場合との違いです。
セルフホスト・BYOC環境で接続先を切り替える
既定の接続先はTurso公式がホストするhttps://mcp.turso.ai/mcpですが、TURSO_MCP_URL環境変数でこのURLを上書きできます。セルフホストやBYOC(Bring Your Own Cloud)構成、あるいは検証用に別のエンドポイントを使いたい場合に使う仕組みで、Claude Code側の設定は同じまま接続先だけを差し替えられます。
よくあるつまずき
- APIキーを探してしまう: Tursoのホスト版MCPサーバーはOAuthのみで、コピーして貼るAPIトークンは存在しません。認証はブラウザの同意画面から行います
claude mcp addで個別登録しようとする: Claude Codeでの推奨導入経路はプラグインマーケットプレイス(/plugin marketplace add→/plugin install)です。手動で.mcp.jsonに書く方法もありますが、公式スキルは付いてきません- 組織を切り替えたのに古いスコープのままになる: 認証情報は明示的にクリアしない限り残ります。
/mcp→ turso → Clear authenticationを実行してから再認証します - 削除や書き込みが拒否される: 認証時に読み取り専用スコープや特定グループだけを選んでいると、書き込み用ツールはTurso API側で拒否されます。書き込みが必要な操作は、フルアクセスまたは書き込み許可のあるグループで認証し直します
まとめ
TursoのMCPサーバーはホスト型1系統(https://mcp.turso.ai/mcp)にOAuthで繋ぐだけで、APIトークンの管理が要りません。認証時に組織・グループ・権限を選ぶことでスコープを絞り、SQL操作は読み取り・書き込み・削除・DDLがツールごとに分かれているため、エージェントが必要以上に強い権限のツールを呼ぶ心配が小さくなります。ポイントインタイムブランチとInsight系の分析ツールを組み合わせれば、過去時点のデータ調査からクエリの遅延分析までを1つの会話で進められます。Claude Code側のMCP登録の基本はClaude Code MCP設定ガイド、OAuthスコープやアクセス範囲の考え方全般はMCPセキュリティガイド、同じくブランチ機能を軸にしたサーバーレスDBの例はNeon MCPサーバーで一時ブランチのマイグレーション検証を回すで扱っています。