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.0 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.
• Imports browser-derived DMS authentication only through explicit local files or standard input.
• 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.
• Automatic extraction of browser cookies or tokens.
• 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.
• 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"

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

2. Start the AliCloud login flow

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

Complete the login in Chrome, open DMS, and confirm completion in the terminal. The CLI stores only a local login assertion. It does not store browser cookies, CSRF tokens, SMS codes, or risk-control tokens.

If DMS is already open in an authenticated Chrome tab, mark the local assertion directly:

uvx --from mcp-alicloud@0.1.0 mcp-alicloud-login complete

3. Import the DMS auth context

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.0 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.0 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.

4. Verify local readiness

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

uvx --from mcp-alicloud@0.1.0 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.

5. Configure an MCP client

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

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.0 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.0", "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.0",
        "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.0 mcp-alicloud-login start --ram-domain "$MCP_ALICLOUD_RAM_DOMAIN"
uvx --from mcp-alicloud@0.1.0 mcp-alicloud-login complete
uvx --from mcp-alicloud@0.1.0 mcp-alicloud-login status
uvx --from mcp-alicloud@0.1.0 mcp-alicloud-login doctor
uvx --from mcp-alicloud@0.1.0 mcp-alicloud-login check
uvx --from mcp-alicloud@0.1.0 mcp-alicloud-login clear

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

DMS auth CLI

uvx --from mcp-alicloud@0.1.0 mcp-alicloud-dms-auth template
uvx --from mcp-alicloud@0.1.0 mcp-alicloud-dms-auth import --input "$HOME/.local/share/mcp-alicloud/dms-auth-context.json"
uvx --from mcp-alicloud@0.1.0 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.0 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.0 mcp-alicloud-dms-auth status --require-dms-web
uvx --from mcp-alicloud@0.1.0 mcp-alicloud-dms-auth doctor --require-dms-web
uvx --from mcp-alicloud@0.1.0 mcp-alicloud-dms-auth check --require-dms-web
uvx --from mcp-alicloud@0.1.0 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

Open DMS in Chrome, capture fresh dms_web and dmsnext requests, import them again, and rerun:

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

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

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.0 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.0 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

• Authentication material is imported explicitly and stored only in a private local file.
• The auth-context file must have mode 0600; its parent directory should have mode 0700.
• 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.
• The server never opens Chrome profiles or browser storage. The user controls every browser-derived import.
• 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.