Overview

This MCP (Model Context Protocol) server connects an MCP-capable agent to AWS Cognito and implements common user authentication flows. It exposes Cognito operations—sign-up, sign-in, password reset, multi-factor verification, session refresh, and user profile management—through MCP tools so an agent or local developer workflow can call them programmatically.

The server is useful when you want to test or prototype authentication flows from an agent (for example Claude/other MCP clients), or when you need a local bridge between an AI assistant and your AWS Cognito User Pool. It runs as a small Node.js service and communicates over stdio per the MCP specification, so it integrates with Claude Desktop, Claude Code, or any MCP client.

Features

Register and confirm users (email/confirmation code)
Sign in and sign out (returns and manages tokens)
Password reset (send verification code and confirm)
Change password for authenticated users
Refresh authentication tokens (refresh token flow)
Update and delete user attributes
Resend confirmation codes and verify TOTP for MFA
Development tooling: inspector for debugging and watch mode for live rebuilds

Installation / Configuration

Prerequisites:

AWS account with a Cognito User Pool and App Client configured
Node.js 18+ installed

Clone, install, and build:

git clone https://github.com/gitCarrot/mcp-server-aws-cognito.git
cd mcp-server-aws-cognito
npm install
npm run build

Environment variables (required):

# .env or exported into the process
AWS_COGNITO_USER_POOL_ID=us-east-1_XXXXXXXXX
AWS_COGNITO_USER_POOL_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx

Run directly (no build, useful for development):

# using tsx / npx to run TypeScript entrypoint
npx tsx src/index.ts

Run the built server:

node build/index.js

Inspector (debugging HTTP UI):

npm run inspector
# Opens a local URL printed in the console for inspecting MCP messages

Watch mode (auto-rebuild during development):

npm run watch

Integrating with Claude Desktop:

Add an MCP server entry in your Claude Desktop developer config:

{
  "mcpServers": {
    "aws-cognito-mcp-server": {
      "command": "/path/to/mcp-server-aws-cognito/build/index.js",
      "env": {
        "AWS_COGNITO_USER_POOL_ID": "us-east-1_XXXXXXXXX",
        "AWS_COGNITO_USER_POOL_CLIENT_ID": "xxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Using with Claude Code (CLI):

# register the MCP server to be launched by the CLI
claude mcp add "aws-cognito-mcp" npx tsx src/index.ts

# list registered MCP servers
claude mcp list

# launch claude with the MCP server available to agents
claude

Available Tools

The server exposes a set of MCP tools that map to Cognito operations. Each tool can be invoked by an MCP-capable client.

Tool name	Purpose	Parameters
`sign_up`	Create a new user in the User Pool	`email` (string), `password` (string)
`sign_up_confirm_code_from_email`	Confirm sign-up with code sent by email	`username`, `confirmationCode`
`sign_in`	Authenticate and return tokens	`username`, `password`
`sign_out`	Sign out current user (revoke local session)	none
`getCurrentUser`	Return currently authenticated user info	none
`reset_password_send_code`	Send password reset code to user	`username`
`reset_password_verify_code`	Complete password reset with code	`username`, `code`, `newPassword`
`change_password`	Change password for signed-in user	`oldPassword`, `newPassword`
`refresh_session`	Exchange refresh token for new tokens	none
`update_user_attributes`	Update attributes like name or phone	`attributes`: [{name, value}, …]
`delete_user`	Delete currently signed-in user from pool	none
`resend_confirmation_code`	Resend sign-up confirmation code	`username`
`verify_software_token`	Verify TOTP code for MFA	`username`, `totpCode`

(Inspector provides a browser-based UI for watching requests/responses while debugging.)

Use Cases

QA and integration testing: Automate sign-up, sign-in, password resets and token refreshing in CI tests that need to interact with Cognito-backed flows.
Agent-assisted account support: Allow an assistant to help users by triggering resend confirmation, look up current user attributes, or generate a password reset flow (instrumented by the agent and gated by policy).
Rapid prototyping: Attach an MCP-capable assistant to test different authentication UX flows (MFA, TOTP) without wiring a full frontend.
Local development for server-side logic: Use this as a lightweight bridge to exercise and debug server-side logic that depends on Cognito authentication.

Notes and Best Practices

Keep AWS credentials and environment variables secure. This repository expects Cognito IDs only; actual AWS SDK calls use standard AWS credentials chain when needed.
Test flows using non-production User Pools or test accounts to avoid impacting real users.
Use the inspector during development to observe the raw MCP messages and simplify debugging when running over stdio.

Repository and source: https://github.com/gitCarrot/mcp-server-aws-cognito

AWS Cognito MCP Server for User Authentication