DynamoDB 읽기 전용 MCP

모델 컨텍스트 프로토콜(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 쿼리 작성을 위한 도움말 프롬프트

설치 및 실행

아래의 Run with NPX 방법을 사용하면 설치 없이 실행할 수 있습니다.

설치

저장소를 복제합니다.지엑스피1
필요한 패키지를 설치하세요:
npm install
.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 구성 파일을 수정해야 합니다.

Claude Desktop 구성 파일을 엽니다.
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
다음과 같이 서버 구성을 추가합니다.
{ "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" } } } }
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"
      }
    }
  }
}

사용 예

클로드에게 다음과 같은 질문을 할 수 있습니다.

"DynamoDB에 어떤 테이블이 있는지 알려주시겠어요?"
"Users 테이블의 구조를 설명하세요"
"groupId가 '0lxp4paxk7'인 'Users' 테이블에서 사용자 수를 찾으세요."

건축학

이 MCP 서버는 다음과 같은 계층 구조로 구성되어 있습니다.

클라이언트 인터페이스(Claude Desktop) - 사용자와 LLM 간의 상호 작용
MCP 프로토콜 계층 - 표준화된 메시지 교환 방법을 제공합니다.
DynamoDB 서버 - DynamoDB와 상호 작용하는 기능을 구현합니다.
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 테이블 목록을 보여주세요"와 같은 질문을 하는 경우:

클로드는 이 요청을 분석하고 list-tables 도구를 호출합니다.
이 요청은 MCP 프로토콜을 통해 서버로 전송됩니다.
서버는 해당 도구 핸들러를 실행합니다.

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}` }] };
  }
});

결과는 MCP 프로토콜을 통해 클로드에게 반환됩니다.
클로드는 이 결과를 자연어로 처리하여 사용자에게 표시합니다.

3. 특정 매개변수 처리

사용자가 "사용자 테이블의 구조를 알려주세요"를 요청하는 경우:

Claude는 이 요청에 describe-table 도구를 사용해야 한다고 결정합니다.
Claude는 매개변수를 { tableName: "Users" } 로 구성합니다.
이 정보는 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',
      },
    ],
  };
});

클로드는 리소스에 접근하여 이를 컨텍스트 정보로 사용합니다.

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 테이블에 대한 쿼리를 작성하는 방법을 보여주세요"라고 요청할 때 사용됩니다.

데이터 흐름 요약

사용자는 자연어로 Claude에게 요청을 합니다.
Claude는 요청을 분석하고 적절한 MCP 도구/리소스/프롬프트를 선택합니다.
MCP 클라이언트는 표준화된 형식으로 서버에 요청을 보냅니다.
서버는 요청을 처리하고 AWS DynamoDB API를 호출합니다.
DynamoDB가 결과를 반환합니다.
서버는 결과를 MCP 형식으로 변환하여 클라이언트로 전송합니다.
Claude는 결과를 자연어로 처리하여 사용자에게 제공합니다.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

DynamoDB Read-Only MCP

Integrations