updsts

A simple CUI tool and local MCP server for reflecting AWS STS credential information into the credential file

English | 日本語

<!-- TOC tocDepth:2..3 chapterDepth:2..6 -->

• 1. Overview
• 2. Features
• 3. Runtime Environment
• 4. Installation / Usage
• 5. Registering as MCP Server
• 6. CUI Tool Command Options
  • 6-1. Common Options
  • 6-2. get Command
  • 6-3. list Command
  • 6-4. mcp Command
• 7. AWS Credentials File
  • 7-1. AWS Credentials File Format
  • 7-2. AWS Credentials File Storage Location
• 8. Available MCP Tools
  • updsts_update_sts_credential
  • updsts_get_credential_info
  • updsts_get_credential_info_list
• 9. Security Notes
• 10. License

<!-- /TOC -->

1. Overview

updsts is a command-line tool that retrieves AWS STS (Security Token Service) credentials from existing AWS credential (.aws/credentials) file information and automatically reflects them in the credential file.
It also has local MCP server functionality that automatically updates temporary credential information in AWS credential files, enabling operation through common Agent tools.

2. Features

• Obtain temporary AWS STS credentials using MFA authentication
• Automatically update AWS credentials file with new session tokens
• Support for TOTP-based MFA devices
• List all AWS profiles in credentials file
• Preserve existing credential profiles safely
• Can be operated from common Agent tools when functioning as a local MCP server.
  (Of course, care is taken to ensure that confidential information such as secret keys and session tokens is not sent to the LLM.)
• Support for proxy environments

3. Runtime Environment

This project uses uv as the package manager.
Using uv allows you to automatically reproduce the runtime environment.

For uv installation, see here:

• Installing uv

4. Installation / Usage

Install and use in a uv environment.

# Install directly from git repository
uv tool install git+{repository_url}

After installation, you can use the updsts command directly as a tool.

updsts --help

5. Registering as MCP Server

By registering as an MCP server, you can operate updsts from common Agent tools.

{
  // Example configuration for registering as MCP server
  //
  // (Note) 
  // Registration keys may differ depending on the Agent tool used,
  // so please refer to the manual of each Agent tool you use for detailed procedures.
  "mcpServers" {
    // Configuration for starting updsts as MCP server using uv
    "updsts-uv": {
      "type": "stdio",
      "command": "updsts",
      "args": [
          "mcp",
          "--mcp-server"
      ],
      "env": {},
    }
  }
}

6. CUI Tool Command Options

6-1. Common Options

• -v, --verbose LEVEL: Set output information detail level (0: normal, 1: verbose, 2: debug)
• -c, --credential-file FILE: Path to the AWS credentials file (default: ~/.aws/credentials)

6-2. get Command

Get and update STS credentials for the specified AWS profile.

updsts get -n <profile_name> -t <totp_token>

• -n, --profile: AWS profile name to get STS token (required)
• -t, --totp-token: TOTP token generated by MFA device (required)
• -sn, --sts-profile-name: STS profile name to generate in AWS credentials file (optional, default: AWS profile name + "_sts")
• -d, --duration: Token duration in seconds (optional, default: 3600)
• -c, --credential-file: Path to credentials file (optional, default: ~/.aws/credentials)

6-3. list Command

Display all AWS profiles in the credentials file.

updsts list

6-4. mcp Command

Start the module as a local MCP server.
You can operate updsts using Agent tools.

updsts mcp --mcp-server

If the --mcp-server option is not specified, it will output the MCP tool list.

updsts mcp

7. AWS Credentials File

7-1. AWS Credentials File Format

updsts works with standard AWS CLI credentials file format.
It preserves existing profiles while updating only the specified sections.

Example credentials file:

[default]
# Access Key ID (required)
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
# Secret Access Key (required)
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLE
# IAM user's MFA device ARN (required. User must add this)
mfa_device_arn = arn:aws:iam::123456789012:mfa/user 
# TOTP secret name managed by mktotp mcp server (optional. User can add this)
# If this is configured and the `mktotp` mcp server is available, Agent will auto-generate and use TOTP token.
totp_secret_name = my_totp_secret 

# The section enclosed by the following tags is automatically created/updated by updsts.
# ${{{ key=<profile name that requested STS> [auto update by updsts]
[default_sts]
aws_access_key_id = ASIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYtempKEY
aws_session_token = IQoJb3JpZ2luX2VjE...
expiration_datetime = 2025-10-05T15:30:00+09:00
# $}}} [auto update by updsts]

updsts automatically manages sections between special tags while leaving other profiles intact.
Tags are automatically added during the first execution, so there is no need to add them manually.

7-2. AWS Credentials File Storage Location

By default, AWS credentials are stored in the following location.
※ This is the same file used by the AWS CLI.

~/.aws/credentials

You can specify a different location with the -c option.

8. Available MCP Tools

When started as an MCP server, the following tools are available from Agent tools.

updsts_update_sts_credential

Get STS credentials for the specified AWS profile and create/update the sts profile in the credential file.

• Parameters:
  • profile_name (str): AWS profile name to update (required)
  • totp_token (str): TOTP token from MFA device (required)
  • sts_profile_name (str | None): STS profile name to create in AWS credentials file (optional)
    • If None or empty string, <profile_name>_sts will be used (default: None)
  • cred_file (str | None): Path to credentials file (optional)
    • If None or empty string, default location (~/.aws/credentials) is used (default: None)
  • duration (int): STS token duration in seconds (optional, default: 3600)
• Returns (dict[str, str] | None): Dictionary containing updated credential details or None if failed

updsts_get_credential_info

Get AWS credential information for the specified profile name in the credential file.
However, for security reasons, aws_secret_access_key and aws_session_token are returned masked.

• Parameters:
  • profile_name (str): AWS profile name to retrieve (required)
  • cred_file (str | None): Path to credentials file (optional)
    • If None or empty string, default location (~/.aws/credentials) is used (default: None)
• Returns (dict[str, str] | None): Dictionary containing credential details or None if not found

updsts_get_credential_info_list

Get AWS credential information for all profiles in the credentials file.
However, for security reasons, aws_secret_access_key and aws_session_token are returned masked.

• Parameters:
  • cred_file (str | None): Path to credentials file (optional)
    • If None or empty string, default location (~/.aws/credentials) is used (default: None)
• Returns (list[dict[str, str]]): List of dictionaries containing credential details or empty list if no profiles found

9. Security Notes

• AWS credentials files contain sensitive information, so protect them with appropriate permission settings (recommended: 600)

10. License

This project is licensed under the MIT License.
See the LICENSE file for details.