DynamoDB Read-Only MCP

DynamoDB 読み取り専用 MCP

Model Context Protocol（MCP）を利用して AWS DynamoDB データベースにクエリを実行するサーバーです。このサーバーを使用すると、Claude などの LLM が自然言語によるリクエストを通じて DynamoDB のデータにクエリを実行できます。

機能

この MCP サーバーは、次の機能を提供します。

• テーブル管理ツール：
  • list-tables：すべての DynamoDB テーブルの一覧を表示します
  • describe-table：特定のテーブルに関する詳細情報を表示します
• データクエリツール：
  • scan-table：テーブルのすべてまたは一部のデータをスキャンします
  • query-table：テーブル内で特定の条件に一致するデータを検索します
  • paginate-query-table：特定の条件に一致するデータを複数のページにわたって取得します
  • get-item：特定のキーを持つ項目を取得します
  • count-items：テーブル内の項目数を計算します
• リソース：
  • dynamodb-tables-info：すべてのテーブルのメタデータを提供するリソースです
  • dynamodb-table-schema：特定のテーブルのスキーマ情報を提供するリソースです
• プロンプト：
  • dynamodb-query-help：DynamoDB クエリの作成を支援するプロンプトです

インストールと実行

以下の NPX で実行 の方法を使えば、インストールせずに実行できます。

Smithery を使用したインストール

Smithery を使用して、Claude Desktop 用の DynamoDB Read-Only Server を自動的にインストールするには：

npx -y @smithery/cli install @jjikky/dynamo-readonly-mcp --client claude

インストール

1. リポジトリをクローンします。

   git clone https://github.com/jjikky/dynamo-readonly-mcp.git
   cd dynamo-readonly-mcp
   

2. 必要なパッケージをインストールします。

   npm install
   

3. .env ファイルを作成し、AWS 認証情報を設定します。

   AWS_ACCESS_KEY_ID=your_access_key
   AWS_SECRET_ACCESS_KEY=your_secret_key
   AWS_REGION=your_region
   

ビルドと実行

npm run build
npm start

Claude Desktop に接続する

この MCP サーバーを Claude Desktop で使用するには、Claude Desktop の設定ファイルを変更する必要があります。

1. Claude Desktop の設定ファイルを開きます。

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 次のようにサーバー設定を追加します。

   {
     "mcpServers": {
       "dynamodb-readonly": {
         "command": "node",
         "args": ["/absolute-path/dynamo-readonly-mcp/dist/index.js"],
         "env": {
           "AWS_ACCESS_KEY_ID": "your_access_key",
           "AWS_SECRET_ACCESS_KEY": "your_secret_key",
           "AWS_REGION": "your_region"
         }
       }
     }
   }
   

3. Claude Desktop を再起動します。

NPX で実行

グローバルにインストールせず、npx を使用してこのサーバーを実行することもできます。

{
  "mcpServers": {
    "dynamodb-readonly": {
      "command": "npx",
      "args": ["-y", "dynamo-readonly-mcp"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your_access_key",
        "AWS_SECRET_ACCESS_KEY": "your_secret_key",
        "AWS_REGION": "your_region"
      }
    }
  }
}

使用例

Claude に次のような質問をできます。

1. 「DynamoDB にどのようなテーブルがあるか教えてください」
2. 「Users テーブルの構造を説明してください」
3. 「groupId が '0lxp4paxk7' である 'Users' テーブル内のユーザー数を調べてください」

---

アーキテクチャ

この MCP サーバーは、次の階層構造で構成されています。

1. クライアントインターフェース（Claude Desktop） - ユーザーと LLM の間のやり取り
2. MCP プロトコルレイヤー - 標準化されたメッセージ交換方式を提供します
3. DynamoDB サーバー - DynamoDB と連携する機能を実装します
4. AWS SDK - AWS DynamoDB サービスと通信します

主な動作の仕組み

1. 初期化と接続

サーバーの起動時に、次の処理が行われます。

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('DynamoDB read-only MCP server is running...');
}

• StdioServerTransport は、標準入出力を通じた通信チャネルを設定します。
• server.connect(transport) は、MCP プロトコルを通じて Claude Desktop に接続します。
• 接続中に、サーバーはサポート対象のツール、リソース、プロンプトに関する情報をクライアントに送信します。

2. ツールリクエストの処理

ユーザーが「DynamoDB テーブルの一覧を表示して」のようなリクエストを Claude に送信すると、次のようになります。

1. Claude がリクエストを分析し、list-tables ツールを呼び出します。
2. このリクエストは MCP プロトコルを通じてサーバーに送信されます。
3. サーバーが対応するツールハンドラーを実行します。

server.tool('list-tables', 'Gets a list of all DynamoDB tables', {}, async () => {
  try {
    const tables = await listTables();
    return {
      content: [{ type: 'text', text: JSON.stringify(tables, null, 2) }],
    };
  } catch (error) {
    return { isError: true, content: [{ type: 'text', text: `Error: ${error.message}` }] };
  }
});

1. 結果が MCP プロトコルを通じて Claude に返されます。
2. Claude がこの結果を自然言語に変換して、ユーザーに提示します。

3. 特定のパラメーターの処理

ユーザーが「Users テーブルの構造を教えて」とリクエストすると、次のようになります。

1. Claude は、このリクエストで describe-table ツールを使用すると判断します。
2. Claude はパラメーターを { tableName: "Users" } に設定します。
3. この情報が MCP サーバーに送信されます。

server.tool(
  'describe-table',
  'Gets detailed information about a DynamoDB table',
  {
    tableName: z.string().describe('Name of the table to get detailed information for'),
  },
  async ({ tableName }) => {
    // Query table information using the tableName parameter
    const tableInfo = await describeTable(tableName);
    // Return results
  }
);

ここで、z.string() は Zod ライブラリを使用してパラメーターを検証します。

4. リソースの処理

リソースは、読み取り専用のデータを提供するもう 1 つの MCP 機能です。

server.resource('dynamodb-tables-info', 'DynamoDB table information', async () => {
  // Create and return resource data
  const tables = await listTables();
  const tablesInfo = await Promise.all(/* Query table information */);

  return {
    contents: [
      {
        uri: 'dynamodb://tables-info',
        text: JSON.stringify(tablesInfo, null, 2),
        mimeType: 'application/json',
      },
    ],
  };
});

Claude はリソースにアクセスし、コンテキスト情報として使用します。

5. プロンプトの処理

MCP サーバーは、特定のタスク向けのプロンプトテンプレートを提供できます。

server.prompt(
  'dynamodb-query-help',
  'A prompt that helps write DynamoDB queries',
  {
    tableName: z.string().describe('Table name to query'),
    queryType: z.enum(['basic', 'advanced']).default('basic'),
  },
  async ({ tableName, queryType }) => {
    // Generate prompt content
    return {
      messages: [
        {
          role: 'user',
          content: { type: 'text', text: helpContent },
        },
      ],
    };
  }
);

このプロンプトは、ユーザーが「Users テーブルへのクエリの書き方を教えて」とリクエストしたときに使用されます。

データフローの概要

1. ユーザーが自然言語で Claude にリクエストします
2. Claude がリクエストを分析し、適切な MCP ツール／リソース／プロンプトを選択します
3. MCP クライアントが標準化された形式でリクエストをサーバーに送信します
4. サーバーがリクエストを処理し、AWS DynamoDB API を呼び出します
5. DynamoDB が結果を返します
6. サーバーが結果を MCP 形式に変換し、クライアントに送信します
7. Claude が結果を自然言語に変換して、ユーザーに提示します

ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。詳細については LICENSE ファイルを参照してください。