mcp-alicloud

mcp-alicloud is a Model Context Protocol server for high-fidelity, read-only Alibaba Cloud Data Management Service (DMS) workflows. It gives MCP clients a structured way to discover passwordless DMS instances and databases, inspect table metadata, run bounded read-only SQL, and handle CSV results.

The implementation follows observed DMS web-console request flows while keeping credentials local and redacting sensitive transport details from tool output.

Important: Version 0.1.3 is an alpha release. It supports a deliberately narrow, read-only subset of DMS. Review the security model before using it with a real cloud account.

This is an independent project and is not an Alibaba Cloud product.

Features

• Lists DMS instances and databases that are already eligible for passwordless access.
• Selects a database for subsequent metadata and SQL operations.
• Searches tables and returns redacted column and index metadata.
• Executes SELECT, SHOW, DESCRIBE, DESC, and EXPLAIN through the DMS precheck, credential, paging, and WebSocket flow.
• Limits interactive result retrieval to 101 rows, including one overflow row used to report truncation.
• Replays the observed DMS front-end CSV conversion locally and can archive a completed CSV downloaded by Chrome.
• Starts a dedicated, persistent Chrome profile through Chrome DevTools MCP and captures the required DMS authentication after interactive login.
• Keeps manual private-file and standard-input auth imports as a recovery path.
• Never reads Chrome profiles, cookie stores, local storage, or browser history.
• Keeps MCP responses structured and removes cookies, tokens, CSRF values, request IDs, raw SQL transport data, and other sensitive fields.

Supported scope

The current release supports:

• Passwordless DMS instances.
• Passwordless databases with the observed COMMON control mode and trusted access flag.
• Read-only table discovery and schema inspection.
• Bounded read-only SQL.
• Local CSV reconstruction that matches the observed DMS front-end conversion.
• Finalization of a CSV file already downloaded through the DMS page in Chrome.

The current release does not support:

• Instance login or database login.
• Permission applications.
• Logged-in or login-required instances and databases.
• DDL, DML, transactions, stored procedure calls, or administrative SQL.
• Direct password submission, SMS-code submission, or private sign-in API replay.
• The “remember this machine for seven days” login option.
• Forged or bulk-replayed telemetry and risk-control requests.

Requirements

• Python 3.13 or newer.
• uv with uvx.
• Node.js 20.19 or newer with npx. The managed login command runs the pinned chrome-devtools-mcp@1.8.0 package.
• Google Chrome for the AliCloud login and DMS console session.
• An Alibaba Cloud RAM account that can access DMS.
• An MCP client with STDIO server support.

The shell examples below use POSIX syntax. Use absolute paths in persistent MCP configuration.

Quick start

1. Create private local directories

Use one session directory for the login CLI, the DMS auth CLI, and the MCP server:

export MCP_ALICLOUD_SESSION_DIR="$HOME/.local/share/mcp-alicloud/session"
export MCP_ALICLOUD_EXPORT_DIR="$HOME/.local/share/mcp-alicloud/exports"
export MCP_ALICLOUD_CHROME_PROFILE_DIR="$HOME/.local/share/mcp-alicloud/chrome-profile"

mkdir -p "$MCP_ALICLOUD_SESSION_DIR" "$MCP_ALICLOUD_EXPORT_DIR" "$MCP_ALICLOUD_CHROME_PROFILE_DIR"
chmod 700 "$MCP_ALICLOUD_SESSION_DIR" "$MCP_ALICLOUD_EXPORT_DIR" "$MCP_ALICLOUD_CHROME_PROFILE_DIR"

2. Sign in and capture DMS authentication

export MCP_ALICLOUD_RAM_DOMAIN="your-account.onaliyun.com"
uvx --from mcp-alicloud@0.1.3 mcp-alicloud-login start --ram-domain "$MCP_ALICLOUD_RAM_DOMAIN" --capture-dms-auth

The command starts a visible Chrome window through the pinned Chrome DevTools MCP provider. Complete the password and MFA steps only in the AliCloud page. Leave the seven-day trusted-device option unchecked.

After AliCloud redirects to DMS, the command automatically:

• Captures and validates the main DMS passwordless-instance request.
• Opens one eligible passwordless database in the DMS SQL Console.
• Captures and validates the DMSNext request context.
• Writes dms-auth-context.json with mode 0600.
• Marks the local login state ready only after the complete auth context passes validation.

The managed browser uses a private persistent Chrome profile. A later refresh can reuse its AliCloud browser session when that session is still valid. The Python process never opens the profile database or decrypts its cookie store; all browser interaction goes through Chrome DevTools MCP.

The default capture timeout is ten minutes and the generated DMS auth context expires after eight hours. Override them only when needed:

uvx --from mcp-alicloud@0.1.3 mcp-alicloud-login start --ram-domain "$MCP_ALICLOUD_RAM_DOMAIN" --capture-dms-auth --capture-timeout-seconds 900 --auth-ttl-hours 12

3. Verify local readiness

uvx --from mcp-alicloud@0.1.3 mcp-alicloud-login doctor

uvx --from mcp-alicloud@0.1.3 mcp-alicloud-dms-auth status --require-dms-web

Both commands return redacted JSON. They report field presence, expiry, file permissions, and readiness without printing secret values.

4. Configure an MCP client

Use one of the configurations below, then restart or reload the MCP client.

Manual auth import fallback

The managed login path is the default. Manual import remains available when Chrome DevTools MCP cannot capture a request after an upstream DMS page change.

The DMS APIs use two related browser contexts:

• dms_web for the main DMS site and passwordless instance listing.
• dmsnext for database metadata, SQL precheck, paging, and execution.

Collect both requests in Chrome DevTools:

1. Open DevTools in the authenticated DMS tab and select the Network panel.
2. Find a successful request to https://dms.aliyun.com/dms/metastore/instances/list.
3. Use Copy as cURL and save the command to a private local file.
4. Open the DMS SQL Console.
5. Find a successful request to https://dmsnext.console.aliyun.com/data/api.json.
6. Use Copy as cURL and save that command to a second private local file.

Treat both cURL files as credentials. Keep them outside the repository, do not paste them into chat, and do not pass their contents as command-line arguments.

Import the files:

umask 077

uvx --from mcp-alicloud@0.1.3 mcp-alicloud-dms-auth import-dms-web-curl --input "$HOME/.local/share/mcp-alicloud/dms-web.curl" --delete-source

uvx --from mcp-alicloud@0.1.3 mcp-alicloud-dms-auth import-dmsnext-curl --input "$HOME/.local/share/mcp-alicloud/dmsnext.curl" --merge-existing --delete-source

The generated auth-context file is written with mode 0600. Import from standard input by passing --input - when a private file is inconvenient.

Codex setup

Codex CLI and the Codex IDE extension share the MCP configuration managed by Codex.

Add the server with Codex CLI

codex mcp add alicloud --env MCP_ALICLOUD_SESSION_DIR="$HOME/.local/share/mcp-alicloud/session" --env MCP_ALICLOUD_EXPORT_DIR="$HOME/.local/share/mcp-alicloud/exports" -- uvx --from mcp-alicloud@0.1.3 mcp-alicloud

codex mcp list

Remove the registration with:

codex mcp remove alicloud

Configure Codex with TOML

Add the following entry to ~/.codex/config.toml. TOML does not expand $HOME, so use absolute paths:

[mcp_servers.alicloud]
command = "uvx"
args = ["--from", "mcp-alicloud@0.1.3", "mcp-alicloud"]
env = { MCP_ALICLOUD_SESSION_DIR = "/Users/you/.local/share/mcp-alicloud/session", MCP_ALICLOUD_EXPORT_DIR = "/Users/you/.local/share/mcp-alicloud/exports" }
startup_timeout_sec = 30
tool_timeout_sec = 120

See the official Codex MCP documentation for current client configuration details.

Generic MCP client setup

Clients that use JSON-based MCP configuration can start the published package with uvx:

{
  "mcpServers": {
    "alicloud": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-alicloud@0.1.3",
        "mcp-alicloud"
      ],
      "env": {
        "MCP_ALICLOUD_SESSION_DIR": "/Users/you/.local/share/mcp-alicloud/session",
        "MCP_ALICLOUD_EXPORT_DIR": "/Users/you/.local/share/mcp-alicloud/exports"
      }
    }
  }
}

The exact configuration file location depends on the client. Keep the package version pinned for reproducible startup.

Run from source

Use the repository environment for local development:

git clone git@github.com:ArtiPyHeart/mcp-alicloud.git
cd mcp-alicloud
uv sync --locked
uv run mcp-alicloud --self-test

Point an MCP client at the checkout:

{
  "mcpServers": {
    "alicloud-dev": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-alicloud",
        "run",
        "mcp-alicloud"
      ],
      "env": {
        "MCP_ALICLOUD_SESSION_DIR": "/Users/you/.local/share/mcp-alicloud/session",
        "MCP_ALICLOUD_EXPORT_DIR": "/Users/you/.local/share/mcp-alicloud/exports"
      }
    }
  }
}

--self-test is only a local smoke test. Do not include it in a real MCP server configuration.

Recommended tool workflow

An MCP client should use the operational tools in this order:

1. get_alicloud_login_status
2. get_dms_auth_context_status
3. list_dms_passwordless_instances
4. list_dms_passwordless_databases
5. select_dms_passwordless_database
6. search_dms_passwordless_tables
7. describe_dms_passwordless_table
8. validate_dms_readonly_sql
9. query_dms_passwordless_sql
10. export_dms_passwordless_sql_csv when a local export is explicitly needed

The selection tool updates the private auth context with the selected database and the matching SQL Console referer. Database-dependent tools validate that selection before making requests.

SQL safety policy

The SQL tools use a conservative read-only policy:

• Allowed first commands: SELECT, SHOW, DESCRIBE, DESC, and EXPLAIN.
• Exactly one statement is accepted.
• SQL comments are rejected.
• DDL, DML, transaction control, permission changes, stored procedure calls, and administrative commands are rejected.
• Side-effecting or high-risk constructs such as delays, file access, advisory locks, sequence mutation, cross-database links, and session-variable assignment are rejected.
• A terminal numeric LIMIT on SELECT must not exceed 101.
• A SELECT without a supported terminal LIMIT is sent through the observed DMS paging endpoint to produce a bounded first-page statement.
• The SQL returned by DMS precheck and paging is validated again before the WebSocket query is sent.
• The WebSocket client stops if more than 101 result rows arrive.
• Tool output defaults to 20 preview rows and allows at most 100 preview rows.

The validator is intentionally strict. It is an application safety layer, not a replacement for least-privilege database credentials or DMS authorization.

CSV handling

There are two distinct CSV paths.

Local DMS-compatible export

export_dms_passwordless_sql_csv executes a bounded read-only query and replays the observed DMS front-end CSV conversion into a local file. When the required DMS web context is available, it also attempts the observed export history request and reports its result separately.

This path is a local reconstruction. It is never reported as a Chrome download. The tool requires an explicitly bounded SELECT with a terminal numeric LIMIT of 101 or less.

Completed Chrome download finalization

finalize_dms_official_csv_download handles a CSV that the DMS page has already downloaded through Chrome into the current user's default Downloads directory. It waits for the file to finish, reads only file metadata, moves it into the configured export directory, and assigns a safe tracking name that contains no SQL, table name, token, account identifier, or result value.

CSV files contain query results and must be protected as sensitive data.

Tool reference

Operational tools

Contract and observation tools

Command-line reference

Login CLI

uvx --from mcp-alicloud@0.1.3 mcp-alicloud-login start --ram-domain "$MCP_ALICLOUD_RAM_DOMAIN" --capture-dms-auth
uvx --from mcp-alicloud@0.1.3 mcp-alicloud-login complete
uvx --from mcp-alicloud@0.1.3 mcp-alicloud-login status
uvx --from mcp-alicloud@0.1.3 mcp-alicloud-login doctor
uvx --from mcp-alicloud@0.1.3 mcp-alicloud-login check
uvx --from mcp-alicloud@0.1.3 mcp-alicloud-login clear

Append --help to any listed command for command-specific options.

DMS auth CLI

uvx --from mcp-alicloud@0.1.3 mcp-alicloud-dms-auth template
uvx --from mcp-alicloud@0.1.3 mcp-alicloud-dms-auth import --input "$HOME/.local/share/mcp-alicloud/dms-auth-context.json"
uvx --from mcp-alicloud@0.1.3 mcp-alicloud-dms-auth import-dms-web-curl --input "$HOME/.local/share/mcp-alicloud/dms-web.curl" --delete-source
uvx --from mcp-alicloud@0.1.3 mcp-alicloud-dms-auth import-dmsnext-curl --input "$HOME/.local/share/mcp-alicloud/dmsnext.curl" --merge-existing --delete-source
uvx --from mcp-alicloud@0.1.3 mcp-alicloud-dms-auth status --require-dms-web
uvx --from mcp-alicloud@0.1.3 mcp-alicloud-dms-auth doctor --require-dms-web
uvx --from mcp-alicloud@0.1.3 mcp-alicloud-dms-auth check --require-dms-web
uvx --from mcp-alicloud@0.1.3 mcp-alicloud-dms-auth clear

Append --help to any listed command for command-specific options.

Environment variables

Troubleshooting

The MCP client cannot find the login state

The login command and MCP server are using different working directories or session paths. Set the same absolute MCP_ALICLOUD_SESSION_DIR for every command and in the MCP client configuration.

The auth context is expired

Run the managed login command again. It reuses the private Chrome profile when the AliCloud browser session remains valid and replaces the expired auth context only after both DMS capabilities pass validation:

uvx --from mcp-alicloud@0.1.3 mcp-alicloud-login start --ram-domain "$MCP_ALICLOUD_RAM_DOMAIN" --capture-dms-auth

The CLI fails closed when required fields are missing, expired, malformed, or stored with unsafe file permissions.

Managed Chrome cannot start

Confirm that Chrome, Node.js, and npx are available. The login command owns its Chrome DevTools MCP process and profile; another process cannot use the same profile directory concurrently. Close the earlier managed login window or pass a different private --chrome-profile-dir, then retry once.

The first run may need network access so npx can install the pinned chrome-devtools-mcp@1.8.0 package into its local cache.

Login reports public asset drift

The login CLI compares public AliCloud page assets with the observed baseline. A drift warning is non-blocking, but it indicates that the browser flow should be reviewed before changing login automation.

A safe query is rejected

Run validate_dms_readonly_sql first and inspect its structured reason. Add a terminal numeric LIMIT when exporting. Interactive queries may omit it because the query tool uses the bounded DMS paging flow.

The MCP server exits or emits protocol errors

Run the local smoke test:

uvx --refresh --from mcp-alicloud@0.1.3 mcp-alicloud --self-test

The normal MCP server uses STDIO. Its standard output is reserved for JSON-RPC; diagnostics are written to standard error.

Upgrading

Update the pinned version in the MCP client configuration, then force an isolated refresh:

uvx --refresh --from mcp-alicloud@0.1.3 mcp-alicloud --self-test

Patch releases use the next 0.1.x version. Keep the server and companion CLI commands on the same package version.

Development

uv sync
uv run python --version
uv run python -m unittest discover -s tests
uv run mcp-alicloud --self-test
uv run pip-audit --local --skip-editable
uv build
uv run twine check dist/*

Runtime code lives in src/mcp_alicloud/; tests use the standard-library unittest runner.

Security model

• The managed login command captures authentication only through its private Chrome DevTools MCP process. Manual file and stdin imports remain explicit recovery paths.
• The auth-context file must have mode 0600; its parent directory should have mode 0700.
• The persistent Chrome profile contains sensitive browser state and must stay in a private 0700 directory. The Python code never opens its databases or decrypts its cookies.
• Cookies, CSRF values, risk-control fields, login tokens, SQL Console credentials, raw WebSocket frames, and raw transport responses are treated as secrets.
• MCP tools return redacted status and bounded business results rather than raw browser state.
• SQL and CSV result data are sensitive even when transport metadata is redacted.
• Authentication failures stop the operation. The implementation avoids blind retries and does not fabricate browser risk-control values.
• Sensitive network-request details are parsed through short-lived private files and deleted immediately. Successful output reports that no raw capture files were retained.
• The project targets real DMS read-only operations. Use a least-privilege RAM account and verify the selected database before running a query.

Never commit .local/, auth-context files, copied cURL commands, exported data, credentials, or browser captures.

Report security issues through the repository's private maintainer channel rather than a public issue.

License

Released under the MIT License.