🤖

TiDBのClaude Desktop用DXT（MCPサーバ）を作成してみた

に公開
Model Context Protocol
TiDB
dxt
tech

TiDBに接続するMCP（DXT）の作成

Claude Desktopに簡単にMCPをインストールできるDXTが発表になったので、vibe codingでTiDB Cloud Serverlessを利用できるDXTを作成しました。

https://github.com/bohnen/tidb-serverless-mcp/releases/tag/v0.2.0

アセットにあるtidb-mcp-0.1.0.dxt をダウンロードして、Claude Desktopの 設定>エクステンション にDrag and Dropすればインストールできます。実際の利用方法はnpakaさんのこの記事に詳しいです。

https://note.com/npaka/n/nb206aa63ac7e

TiDB Cloud Serverlessのクラスタ接続情報が必須になりますので、クラスタを作成して接続情報を取得しておいてください。初めて使う人はこちらの記事を参考にすると良いと思います。

https://zenn.dev/kameoncloud/articles/e81735bb6bbdac

TiDB Cloud Serverlessに接続するためにTiDB Cloud Serverless Driverを使って接続しているため、別途MCPサーバを立てる必要がないところもポイントです。本当にインストールするだけで利用できます。

この記事の残りはどうやって作ったかということのメモになります。

DXTの作成

Claude CodeにDXTを作成させるためのプロンプト

本家ClaudeのDXTの発表ブログの中に、Claude CodeでDXTを作成するためのプロンプトが記載されています。

https://www.anthropic.com/engineering/desktop-extensions

このプロンプトは実際にはMCPをDXTにパッケージングするために必要なmanifest.jsonだけではなく、プロジェクト全体を生成します。（MCPは時刻を返すものとか、ターミナルにアクセスするものとかです）。

ここではanthropicのgithub中のサンプルや、READMEを参照することでDXTファイルの構成や実装方法を学ばせています。ならば、既存のMCPがあれば同じように参照することでDXTファイル化することができそうです。

既存のMCP - PyTiDB MCP Extension

TiDBにアクセスするMCPとして、PyTiDB MCP Extensionがあります。

https://pingcap.github.io/ai/integrations/tidb-mcp-server/

当初はこちらにmanifest.jsonをくっつけてDXT化しようとおもったのですが、想像以上に依存関係が多く、複数環境でちゃんと動かすのは容易でなさそうです。

幸い、TiDB Cloud Serverless専用にはなりますが、httpsでDBに接続するTiDB Cloud Serverless Driverというものがあります。これならNode.jsだけなので、Claude Desktop単独で動作できるでしょう。

プロンプトはpytidbのmcpのものを利用し、実際のDBアクセスをServerless Driverでやることにします。

プロンプトの修正

以上から、anthropicのプロンプトに作るものの指定と、参照にpytidbのmcpソース、それからServerless DriverのREADMEを加え、プロジェクトを生成させました。実際に利用したプロンプトはこちらにあります。

https://github.com/bohnen/tidb-serverless-mcp/blob/main/instruction.md

先頭の指示文を少々、
0. Understand the requirements:と1.Read the specifications thoroughly: を書き換えただけです。

Claude Codeを利用しプロジェクトを生成すると、ほぼ一発でちゃんと動くものができてきました。

manifest.json の修正

自動生成されたmanifest.jsonは、勝手にTiDB接続に必要なパラメーターなどをユーザー定義変数として指定してくれます。ただ、フォーマットが違っていたり、適当なダミーが入っていたりするので修正する必要があります。dxt validateコマンドでチェックすると、間違っているところを教えてくれるので修正します。

  • バージョン番号
  • 作成者
  • ユーザー定義変数

などが、主な修正箇所です。

MCPに環境変数を渡す際には、ユーザー定義変数の値を渡す必要がありますが、これは次のように記載します。

  "server": {
    "type": "node",
    "entry_point": "dist/server.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/dist/server.js"],
      "env": {
        "TIDB_HOST": "${user_config.host}",
        "TIDB_PORT": "${user_config.port}",
        "TIDB_USERNAME": "${user_config.username}",
        "TIDB_PASSWORD": "${user_config.password}",
        "TIDB_DATABASE": "${user_config.database}"
      }
    }
  },

${user_config.hogehoge} のように、ユーザー定義変数の変数名を指定して、値を取得します。

パッケージング

validateが通ると、パッケージングができます。パッケージングは、dxt packでできます。

! dxt pack
  ⎿  Validating manifest...
     Manifest is valid!

     📦  tidb-cloud-serverless@0.1.0
     Archive Contents
         512B .claude/settings.local.json
        2.7kB CLAUDE.md
       12.4kB dist/server.js
        2.4kB instruction.md
        3.5kB manifest.json
         374B mcp.json.example
        1.7kB node_modules/bytes/History.md
        3.5kB node_modules/bytes/index.js
        1.1kB node_modules/bytes/LICENSE
         959B node_modules/bytes/package.json
...

こんな感じで、ディレクトリ以下一切合切（例外はある）アーカイブされるので注意してください。.gitignoreに書いたものはアーカイブされないかな？テストの時に利用した接続情報などがパッケージングされないように気をつけます。

これでDXTファイルが完成です。あとはClaude Desktopに組み込んで試していきます。

DXTのデバッグ

Claude Desktopに組み込んだときにエラーになる場合があります。
macosの場合は ~/Library/Logs/Claude/ にログが出力されています。Claude Desktopのログ(main.log)と、DXTごとのログが出力されているのでログを確認します。

ここで重要なのは、ソースコードでエラーログを吐くようにしていても、manifest.jsonの不備で起動しない場合はログが出力されない という点です。次のようなログが典型的なケースです。

2025-07-06T14:29:34.195Z [TiDB Cloud Serverless] [info] Initializing server... { metadata: undefined }
2025-07-06T14:29:34.201Z [TiDB Cloud Serverless] [info] Using built-in Node.js for MCP server: TiDB Cloud Serverless { metadata: undefined }
2025-07-06T14:29:34.206Z [TiDB Cloud Serverless] [info] Server started and connected successfully { metadata: undefined }
2025-07-06T14:29:34.248Z [TiDB Cloud Serverless] [info] Message from client: {"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"claude-ai","version":"0.1.0"}},"jsonrpc":"2.0","id":0} { metadata: undefined }
2025-07-06T14:29:34.807Z [TiDB Cloud Serverless] [info] Server transport closed { metadata: undefined }
2025-07-06T14:29:34.807Z [TiDB Cloud Serverless] [info] Client transport closed { metadata: undefined }
2025-07-06T14:29:34.807Z [TiDB Cloud Serverless] [info] Server transport closed unexpectedly, this is likely due to the process exiting early. If you are developing this MCP server you can add output to stderr (i.e. `console.error('...')` in JavaScript, `print('...', file=sys.stderr)` in python) and it will appear in this log. { metadata: undefined }
2025-07-06T14:29:34.807Z [TiDB Cloud Serverless] [error] Server disconnected. For troubleshooting guidance, please visit our [debugging documentation](https://modelcontextprotocol.io/docs/tools/debugging) { metadata: { context: 'connection', stack: undefined } }

MCPでSTDIOに接続した直後にログ書いてるのに出力されない・・・何故・・・となりますが、manifest.jsonに間違いがあるとこのようになります。私の場合はユーザー定義変数を削除したにもかかわらず、MCPサーバのenv設定で参照していたのが問題でした。

まだ不明なところ

DXTはバージョンアップは自動でできると書いてあるのですが、どこでその情報を登録するのかがわかりません。ドキュメントをざっと探した感じでは見当たりません。

ただMCP起動時に毎回下記のようにチェックを行っているので、何かしら登録するAPIなどがありそう（公開されてきそう）です。ウォッチしていきたいと思います。

2025-07-06 22:21:38 [info] Failed to fetch from DXT directory: {
  url: 'https://claude.ai/api/organizations/91e6d73c-478e-461e-aea3-084ddadec0bc/dxt/extensions/local.dxt.desktop-tools-team.desktop-tools/versions',
  status: 404,
  statusText: ''
}

Discussion