DynamoDB Read-Only MCP

DynamoDB 只读 MCP

一个利用 Model Context Protocol（MCP）查询 AWS DynamoDB 数据库的服务。此服务允许 Claude 等大模型通过自然语言请求查询 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 查询的帮助提示词

安装与运行

你可以使用下方的 Run with 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

若要在 Claude Desktop 中使用此 MCP 服务，需要修改 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. “找出 'Users' 表中 groupId 为 '0lxp4paxk7' 的用户数量”

---

架构

此 MCP 服务由以下分层结构组成：

1. 客户端接口（Claude Desktop） - 用户与大模型之间的交互
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. 工具请求处理

当用户向 Claude 提出类似“显示 DynamoDB 表列表”的请求时：

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. 资源处理

资源是 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 文件。