Amplify Data API MCP Server

This MCP (Model Context Protocol) server lets you interact with your AWS Amplify Gen2 application's data through natural language. It allows AI assistants like Claude to perform operations on your Amplify data models using conversational language instead of complex code or commands.

Features

• 💬 Natural Language Interface: Ask questions and give instructions in plain English
• 🔍 View Schema Information: List models, view field details, and explore relationships
• 📊 Query Data: Run custom GraphQL queries to list and retrieve your data
• ✏️ Modify Data: Create, update, and delete records through GraphQL mutations
• 🔐 Secure Authentication: Uses Cognito authentication with environment variables

Important Authentication Requirements

This MCP server uses Cognito authentication to access your Amplify data. Your Amplify project must be configured to use Cognito-based authentication. The server will only have access to data models and records that the authenticated user has permission to access.

For optimal functionality, we strongly recommend:

1. Creating an ADMINS user group in your Cognito user pool
2. Adding appropriate users to this group
3. Configuring your Amplify models with permissions that allow the ADMINS group to perform all operations

Example model authorization for admin access:

// In your Amplify model definition
authorization: (allow) => [
  allow.authenticated().to(["read"]),
  allow.group("ADMINS").to(["create", "read", "update", "delete"]),
];

Without proper admin permissions, the MCP server will be limited in what it can do with your data.

Setup Instructions

Prerequisites

• Node.js v16 or higher
• An AWS Amplify Gen2 app with data models
• Access to your Amplify outputs file (amplify_outputs.json)
• Cognito authentication configured in your Amplify app
• A user with appropriate permissions (ideally in the ADMINS group)

Installation

1. Clone the repository:

   git clone https://github.com/dbsmith7491/aws-amplify-data-mcp.git
   cd aws-amplify-data-mcp
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration for Claude Desktop

To use this with Claude Desktop:

1. Open Claude Desktop configuration file:

   • Mac/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %AppData%\Claude\claude_desktop_config.json

   Create the file if it doesn't exist.

2. Add the Amplify MCP server configuration:

   {
     "mcpServers": {
       "amplify-data-api": {
         "command": "node",
         "args": [
           "/ABSOLUTE/PATH/TO/aws-amplify-data-mcp/build/index.js",
           "--amplify-outputs",
           "/ABSOLUTE/PATH/TO/YOUR/amplify_outputs.json"
         ],
         "env": {
           "AMPLIFY_USERNAME": "your-admin-username",
           "AMPLIFY_PASSWORD": "your-admin-password"
         }
       }
     }
   }
   

   Replace the paths and credentials with your own. For full functionality, use credentials for a user in the ADMINS group.

3. Restart Claude Desktop

Using Natural Language with Your Data

Once configured, you can interact with your Amplify data using everyday language in Claude. Simply include the @amplify-data-api tag at the beginning of your message to direct your question to the Amplify server.

Natural Language Examples

Here are some examples of how you can interact with your data:

• "@amplify-data-api What data models do I have in my application?"
• "@amplify-data-api Show me what fields the Story model has"
• "@amplify-data-api Can you list all stories in my database?"
• "@amplify-data-api Find stories that have 'adventure' in the title"
• "@amplify-data-api Create a new character named 'Claude' who is an AI assistant"
• "@amplify-data-api Update the story with ID 'abc123' to change its title to 'The Journey Begins'"
• "@amplify-data-api Delete the Story with ID 'xyz789'"
• "@amplify-data-api What's the relationship between Characters and Stories?"
• "@amplify-data-api Show me all the characters in story 'abc123'"
• "@amplify-data-api How many stories have been created in the last month?"

Claude will interpret these natural language requests and convert them into the appropriate GraphQL queries and mutations.

Available Tools

The server provides the following tools:

1. List all data models:

   • Lists all available data models in your Amplify app

2. Get model details:

   • Shows detailed information about a specific model's fields and relationships

3. Run GraphQL queries and mutations:

   • Execute custom GraphQL queries and mutations for maximum flexibility
   • Handles all data operations (list, get, create, update, delete)

4. Get relationship details:

   • Shows relationships between models for complex data structures

5. List enums:

   • Shows all enum types available in your data models

6. Manual login (if needed):

   • Authenticate manually if automatic authentication fails

Example Conversations

Here's how a typical conversation with Claude might flow:

You: @amplify-data-api What data models do I have available?

Claude: I'll check your Amplify app for available data models.

I found the following models:

• Story
• Character
• Location
• World [more details about each model...]

You: @amplify-data-api Tell me about the Story model

Claude: Here are the details for the Story model:

Fields:

• id: ID (required)
• title: String (required)
• description: String
• numberOfPages: Int [other fields...]

You: @amplify-data-api Can you create a new Story called "Claude's Adventure" about an AI exploring a magical world?

Claude: I'll create that Story for you using a GraphQL mutation. Here's what I'll submit:

mutation CreateStory {
  createStory(
    input: {
      title: "Claude's Adventure"
      description: "A tale about an AI exploring a magical world"
      status: "draft"
    }
  ) {
    id
    title
    description
    status
    createdAt
    updatedAt
  }
}

You: Yes, please create it

Claude: I've created the Story! Here's the new record:

{
  "id": "abc123",
  "title": "Claude's Adventure",
  "description": "A tale about an AI exploring a magical world",
  "status": "draft",
  "createdAt": "2023-06-15T10:30:45Z",
  "updatedAt": "2023-06-15T10:30:45Z"
}

You: @amplify-data-api Now let's add a character to this story

Claude: [continues the interaction naturally...]

Security Considerations

• Credentials in Environment Variables: Uses environment variables for better security of credentials
• Permissions: Use appropriate Cognito groups to control access (ADMINS group for full access)
• Data Sensitivity: Be mindful of what data you access through AI assistants
• Access Control: The MCP server can only access data that the authenticated user has permission to access
• User Roles: For full functionality, use credentials for a user with admin privileges

Troubleshooting

• Authentication Issues: Verify your Cognito credentials and user pool settings
• Missing Models: Ensure your amplify_outputs.json file is up-to-date
• Connection Problems: Check Claude Desktop logs for errors
• Permissions Errors: Verify your user has appropriate permissions in Cognito
• Limited Access: If you can't see certain models or records, check if your user has permission to access them

For Developers

• TypeScript source is in the src/ directory
• Compiled JavaScript is output to build/
• Run npm run build after any source code changes

Distribution as a ZIP File

If you receive this project as a ZIP file, follow these steps to get it working:

1. Extract the ZIP file to a directory on your computer
2. Open a terminal and navigate to the extracted directory
3. Install dependencies:

   npm install
   

4. Build the project:

   npm run build
   

5. Configure Claude Desktop with the correct paths and environment variables as shown in the "Configuration for Claude Desktop" section above
6. Restart Claude Desktop to apply the changes

If you want to distribute this project to others:

1. Ensure all changes are committed
2. Include all necessary files:
   • src/ directory with all TypeScript source files
   • package.json and other configuration files
   • This README.md file
   • (Optionally) the build/ directory if you've already built the project
3. Create a ZIP file of the entire directory
4. Share the ZIP file with instructions to follow the steps above

Command Line Options

Options:
  --amplify-outputs <path>   Path to the amplify_outputs.json file
  --help, -h                 Show this help message

Environment Variables:
  AMPLIFY_USERNAME           Cognito username for automatic login
  AMPLIFY_PASSWORD           Cognito password for automatic login

Additional Resources

• Amplify Gen2 Documentation
• Amplify Authentication Documentation
• Model Context Protocol Documentation
• Claude Desktop Documentation

---

Need more help? Contact your development team for support.