Claude Media
Turso MCPサーバーでOAuth接続のエッジSQLiteを管理する
Claude CodeMCPClaude連携チュートリアル

Turso MCPサーバーでOAuth接続のエッジSQLiteを管理する

TursoのホストMCPサーバーをOAuthだけで接続し、組織・グループ単位のスコープ設定とブランチ機能をClaude Codeから使う手順をまとめます。

読了目安 約9分

Tursoは、SQLite互換のデータベースです。クラウド版のTurso Cloudでは、ブランチ機能付きの管理を提供します。TursoのMCPサーバーはhttps://mcp.turso.ai/mcpにホストされた1系統だけで、認証はOAuth 2.1です。他のMCPサーバーに多い「APIキーを発行してコピーする」手順が無く、ブラウザでの同意画面を通すだけで接続できます。フィーチャーフラグ基盤のStatsigは、Statsig MCPサーバーでOAuthとAPIキーの両方に対応しており、ここが違います。

Tursoという名前は3つのものを指すので、先に切り分けておきます。公式プラグインに同梱されるスキル(skills/turso/SKILL.md)は、次のように使い分けています。

用語

Tursoの3つの呼び名

  • Turso(エンジン)

    SQLite互換のデータベースエンジンです。ローカル・埋め込み用途のほか、Turso Cloudのエンジンとしても選べます。ローカル用のパッケージは@tursodatabase/database(JavaScript)、pyturso(Python)、tursoクレート(Rust)です。

  • libSQL

    SQLiteの古いフォークです。新規のTurso Cloudデータベースの既定エンジンで、各言語のlibSQLドライバはローカルとリモートの両方に接続できます。

  • Turso Cloud

    組織・グループ・ホスト型データベースを管理するプラットフォームです。このMCPサーバーが操作するのはここで、エンジンの挙動を直接いじるものではありません。

アプリ側の接続コードは別に用意します。Turso Cloudへリモート接続する場合、JavaScriptなら@tursodatabase/serverlessがlibSQLとTursoのどちらのデータベースにも使えます。DrizzleやPrismaと組み合わせる既存コードでは@libsql/clientも引き続き動きます。MCPサーバーが担当するのは、クラウド側のリソース管理とSQL実行です。

エンジンは作成時に選べます。create_databaseをuse_tursodb: true付きで呼ぶとTursoエンジンになります。既存のデータベースがどちらのエンジンかは、list_databasesが返すengineフィールド("tursodb"か"libsql")で分かります。ローカルとの同期には@tursodatabase/syncを使います。ただしクラウド側もTursoエンジンである必要があり、libSQLは同期に推奨されません。

Claude Codeへプラグインで導入する

Claude Codeでは、Turso公式のプラグインマーケットプレイスから入れます。

手順

導入から認証までの4手順

  1. 1

    マーケットプレイスを追加する

    下のコマンドの1行目をClaude Codeのプロンプトで実行します。

  2. 2

    プラグインを入れる

    続けて2行目を実行します。MCPサーバーの設定と、エンジン選択やドライバの使い分けを補助するスキルが一括で入ります。

  3. 3

    Authenticateを選ぶ

    /mcpでtursoを選び、Authenticateを押すとブラウザが開きます。

  4. 4

    同意画面でスコープを決める

    Tursoにログインし、組織・グループ・権限を選んで承認します。トークンはClaude Codeが安全に保管し、自動で更新します。TursoのREADMEはOSのキーチェーンに保存されると説明しています。

/plugin marketplace add tursodatabase/turso-mcp
/plugin install turso@turso

接続先のサーバーは1つですが、パッケージングはエージェントごとに用意されています。Codexならcodex plugin marketplace add tursodatabase/turso-mcpでプラグインを追加します。続けてcodex plugin add turso@tursoを実行し、codex mcp login tursoで認証します。Cursorは、Customize → Pluginsからマーケットプレイスを追加します。URLはhttps://github.com/tursodatabase/turso-mcpで、入れるのはTursoです。そのうえでSettings → MCPのログインプロンプトに従います。

Claude(Claude.aiやClaude Desktop)からも使えます。Settings → Connectors → Add custom connectorを開き、https://mcp.turso.ai/mcpを指定します。

プラグインを使わず.mcp.jsonに直接書く

プラグインを使わず、プロジェクトの.mcp.jsonへ書く方法もあります。

{
  "mcpServers": {
    "turso": {
      "type": "http",
      "url": "https://mcp.turso.ai/mcp",
      "oauth": { "clientId": "turso-mcp" }
    }
  }
}

この方法ではスキルが付いてきません。clientIdのturso-mcpは秘匿する値ではなく、公開クライアントを識別するラベルです。Turso側は、安全性の根拠をクライアントIDの秘匿ではなくPKCE・リダイレクト先・ログインに置いています。

Claude Code v2.1.287のclaude mcp add --helpには、--client-id <clientId>と--callback-port <port>が並びます。コマンドラインから同じ登録をしたいときは、これらで事前登録のクライアントIDを渡せます。Claude Codeのドキュメントも、.mcp.jsonのoauth.clientIdと--client-idを同じ設定の別の書き方として扱っています。

「APIトークンを発行しなくていい」のは、エンドポイントを自動で見つける仕組みがあるからです。サーバーURLだけを渡すと、Claude CodeはWWW-Authenticateヘッダーのチャレンジを読みます。そこから保護対象リソースのメタデータ、認可サーバーのメタデータの順に辿ります(RFC 9728とRFC 8414)。ホスト型のクライアントなら動的クライアント登録も使えますが、Claude Codeは共有の公開クライアントID(turso-mcp)で動きます。

接続後は、次のような頼み方がそのままツール呼び出しになります。

  • 「自分のデータベース一覧を見せて」
  • 「prodグループに新しいデータベースを作って」
  • 「app-dbを昨日時点のブランチとして切って」
  • 「app-dbで一番遅いクエリはどれ」
  • 「usersテーブルにインデックスを追加して」

同意画面で、グループか組織全体かを選ぶ

認証時にブラウザで開く同意画面では、まず組織を選び、そのうえでアクセス範囲を2通りから決めます。

くらべる

トークンの範囲

最小権限

グループを1つ選ぶ

そのグループのリソースだけにトークンが絞られます。権限は読み取り専用・フルアクセス・カスタムの3種類から選べます。

フルアクセス

組織全体を選ぶ

組織内のすべてを対象にしたトークンになります。権限の細かい選択肢は、グループ選択のときだけ出ます。

どちらを選んでも、トークンはTurso側のAPIで組織との紐付け・ロール・スコープを毎回チェックされ、操作は監査ログに記録されます。MCPサーバー自体は権限を判断せず、受け取ったトークンをそのままTurso Platform APIへ転送する薄い層です。未スコープのトークンはAPI側で拒否されます。

組織やスコープを選び直したいときは、Claude Codeなら/mcp → turso → Clear authenticationで認証をクリアしてから、もう一度認証します。

SQL操作がツールごとに分かれている理由

Turso MCPサーバーは、SQLの実行を1つの万能ツールにまとめていません。読み取り専用クエリ、書き込み(INSERT/UPDATE)、削除、スキーマ変更(DDL)が別々のツールです。エージェントは、その場でいちばん権限の弱いツールを選べます。

書き込み用のツールはDELETEとDROPを拒否します。削除には、名前から意図が分かる専用ツールがあります。読み取り専用の操作と破壊的な操作には注釈が付いているので、エージェントは両者を区別し、データを変える操作の前に確認を挟めます。

データベース管理・分析・復元のツール

データベース関連のツールは、一覧・詳細確認・作成・削除のほか、ブランチ作成とブランチ一覧、設定変更までを扱います。管理系のツール名はlist_databases、get_database、create_database、delete_databaseです。ブランチと設定はcreate_branch、list_branches、set_database_configです。分析はdatabase_analytics、SQLはread_database、write_database、delete_from_database、evolve_schemaに分かれています。設定変更の対象は、削除保護・IP/VPCの許可リスト・サイズ上限です。ブランチ作成には、過去の任意の時点を指定するポイントインタイムブランチが含まれます。

分析用のInsight系ツールは、データベースごとのクエリ頻度とレイテンシーの上位を返します。SQLを書かずに、遅いクエリの調査を頼めます。

見落としやすいのが復元用のツールです。Turso Cloudは、削除したデータベースとグループを削除から最大5日間は復元できる状態で保持します。MCPサーバーにも、この期間内に削除されたものの一覧と復元のツールがあります。データベースはlist_deleted_databasesで一覧を取り、返ってきたUUIDをrestore_databaseに渡します。このとき別名を付けて復元することもできます。グループはlist_deleted_groupsとrestore_groupの組で、グループと一緒に削除されたデータベースもまとめて戻ります。一部のデータベースの復元に失敗しても、グループ自体は有効になります。失敗分はrestore_databaseで個別にやり直せます。なお、削除済みの一覧に載っていても、リージョンの対応状況によっては復元できないことがあります。チームメイトやスクリプト、エージェントによる誤削除に備える機能です。

復元には条件があります。有料プランで、組織のadminまたはownerの権限があり、組織側で復元(Allow restore)が有効になっている必要があります。復元されるのは削除した瞬間の状態で、名前もデータも同じです。既存データベースを過去の時点へ戻すポイントインタイムリカバリとは別の機能で、そちらは削除済みのデータベースを復活させられません。

セルフホスト・BYOC環境で接続先を切り替える

既定の接続先はhttps://mcp.turso.ai/mcpで、TURSO_MCP_URL環境変数で上書きできます。セルフホスト、BYOC(Bring Your Own Cloud)構成、検証用のエンドポイントに向けたいときの仕組みです。

この変数を読むのは、プラグインが持つ.mcp.jsonです。そこではurlが${TURSO_MCP_URL:-https://mcp.turso.ai/mcp}と書かれていて、未設定なら既定のURLに落ちます。上の手書きの例のようにURLを固定した場合、環境変数は効きません。手書きの設定で切り替えたいなら、同じ${変数名:-既定値}の形をurlに書きます。Claude Codeの.mcp.jsonはこの展開に対応しています。

よくあるつまずき

  • claude mcp addだけで登録して、スキルが入らない: 手動登録ではMCPサーバーの設定だけが入ります。スキルまで欲しいときは、/plugin install turso@tursoを使います
  • 書き込みや削除が拒否される: 読み取り専用スコープや特定グループだけで認証していると、書き込み用ツールはTurso API側で拒否されます。フルアクセス、または書き込み許可のあるグループで認証し直します
  • 削除したデータベースを戻せない: 対象は、有料プランの間に削除してから5日以内のものだけです。組織側で復元(Allow restore)を無効にしている場合も、管理者が有効に戻すまで復元できません

まとめ

APIトークンを持たないぶん、判断は同意画面に集まります。普段の調査はグループ限定の読み取り専用、削除や設定変更が要る作業だけ権限を上げて認証し直す、という使い分けができます。

Claude Code側のMCP登録の基本はClaude Code MCP設定ガイド、OAuthスコープの考え方全般はMCPセキュリティガイドにあります。ブランチ機能を軸にしたサーバーレスDBの例はNeon MCPサーバーで一時ブランチのマイグレーション検証を回すにあります。書き込みクエリにWHERE句必須やDDL確認といった安全策を設けたDB向けサーバーはPlanetScale MCPサーバーの使い方で扱っています。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →