updsts

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

English | 日本語

• updsts
  • 1. Overview
  • 2. Features
  • 3. Runtime Environment
  • 4. Installation/Usage
    • 4-1. Install as a uv tool
      • 4-1-1. Installation
      • 4-1-2. Registering as an MCP server
    • 4-2. Registering as an MCP server via the Claude plugin
  • 5. CUI Tool Command Options
    • 5-1. Common Options
    • 5-2. get Command
    • 5-3. list Command
    • 5-4. mcp Command
  • 6. Credentials File
    • 6-1. Credentials File Format
    • 6-2. Credentials File Location
  • 7. Available MCP Tools
    • updsts_update_sts_credential
    • updsts_get_credential_info
    • updsts_get_credential_info_list
  • 8. Security Notes
  • 9. License

1. Overview

updsts is a command-line tool that retrieves AWS STS (Security Token Service) credentials using the credentials already registered in an existing credentials file (~/.aws/credentials). The retrieved credentials are automatically reflected in the same file.
It also works as a local MCP server that automatically updates the temporary credentials in the credentials file, so it can be operated from common Agent tools.

2. Features

• Obtain temporary AWS STS credentials using MFA authentication
• Automatically update the STS profile in the credentials file with the new credentials
• Support for TOTP-based MFA devices
• List all AWS profiles in the credentials file
• Leave profiles other than the one being updated untouched
• Can be operated from common Agent tools when running 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 reproduce the runtime environment automatically.

For how to install uv, see:

• Installing uv

4. Installation/Usage

4-1. Install as a uv tool

Install updsts into a uv environment and use it.
Use this method when you use updsts as a CUI tool.

4-1-1. Installation

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

After installation, you can run the updsts command directly.

updsts --help

4-1-2. Registering as an MCP server

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

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

4-2. Registering as an MCP server via the Claude plugin

updsts can be installed as a Claude plugin.

# Add the marketplace
/plugin marketplace add zv-louis/zv-plugin-marketplace
# Install from the marketplace
/plugin install updsts-mcp@zv-plugins

5. CUI Tool Command Options

5-1. Common Options

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

5-2. get Command

Get and update the STS credentials for the specified AWS profile.

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

• -n, --profile_name: AWS profile name to get the STS token for (required)
• -t, --totp_token: TOTP token generated by the MFA device (required)
• -sn, --sts_profile_name: STS profile name to create in the credentials file (optional, default: AWS profile name + "_sts")
• -d, --duration: Token duration in seconds (optional, default: 3600)
• -c, --credential_file: Path to the credentials file (optional, default: ~/.aws/credentials)

5-3. list Command

Display all AWS profiles in the credentials file.
Secrets (aws_access_key_id, aws_secret_access_key, aws_session_token) are displayed masked.

updsts list

5-4. mcp Command

Start updsts as a local MCP server.
You can operate updsts from Agent tools.

updsts mcp --mcp-server

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

updsts mcp

6. Credentials File

6-1. Credentials File Format

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

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. The user must add this)
mfa_device_arn = arn:aws:iam::123456789012:mfa/user 
# TOTP secret name managed by the mktotp MCP server (optional. The user can add this)
# If this is set and the `mktotp` MCP server is available, the Agent will automatically generate and use the TOTP token.
totp_secret_name = my_totp_secret 

# The section enclosed by the following tags is automatically created/updated by updsts.
# ${{{ key=<name of the profile 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 the section between the special tags and leaves other profiles intact.
The tags are added automatically on the first run, so there is no need to add them manually.

6-2. Credentials File Location

By default, the credentials file is 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.

7. Available MCP Tools

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

updsts_update_sts_credential

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

• Parameters:
  • profile_name (str): AWS profile name to update (required)
  • totp_token (str): TOTP token from the MFA device (required)
  • sts_profile_name (str | None): STS profile name to create in the credentials file (optional)
    • If None or an empty string, <profile_name>_sts is used (default: None)
  • cred_file (str | None): Path to the credentials file (optional)
    • If None or an empty string, the default location (~/.aws/credentials) is used (default: None)
  • duration (int): STS token duration in seconds (optional, default: 3600)
• Returns (dict[str, str] | None): A dictionary containing the update result, or None on failure
  • updated_profile_name: Name of the STS profile that was updated
  • aws_access_key_id: Access key ID of the retrieved STS credentials (masked)
  • aws_token_expiration: Expiration of the STS credentials (ISO 8601 format in the local time zone)
  • The secret access key and the session token are not returned

updsts_get_credential_info

Get the information of the specified AWS profile in the credentials file.
For security reasons, aws_access_key_id, 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 the credentials file (optional)
    • If None or an empty string, the default location (~/.aws/credentials) is used (default: None)
• Returns (dict[str, str] | None): A dictionary containing the credential details, or None if not found

updsts_get_credential_info_list

Get the information of all AWS profiles in the credentials file.
For security reasons, aws_access_key_id, aws_secret_access_key and aws_session_token are returned masked.

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

8. Security Notes

• The credentials file contains sensitive information, so protect it with appropriate permissions (recommended: 600)

9. License

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