alibabacloud-sls-mcp-proxy 0.1.0a1

Local MCP proxy for Alibaba Cloud Simple Log Service

Alibaba Cloud SLS MCP Proxy

简体中文 | English

alibabacloud-sls-mcp-proxy connects local Model Context Protocol (MCP) clients to Alibaba Cloud Simple Log Service (SLS). It signs each upstream request with your Alibaba Cloud credentials while keeping the MCP connection on your machine.

The proxy supports:

• stdio transport for desktop MCP clients and IDEs;
• a loopback-only Streamable HTTP transport;
• static AccessKey credentials with an optional STS token;
• credentials from an Alibaba Cloud CLI profile, including refresh of temporary credentials close to expiration.

Requirements

• Python 3.10 or later;
• Alibaba Cloud credentials that are authorized to use the SLS MCP service;
• Alibaba Cloud CLI when using --profile.

uv is recommended for running the proxy without a permanent installation.

Installation

Run the latest release directly with uvx:

uvx alibabacloud-sls-mcp-proxy@latest --profile default

Alternatively, install the command in an isolated environment:

uv tool install alibabacloud-sls-mcp-proxy
alibabacloud-sls-mcp-proxy --help

The package can also be installed with pipx or pip:

pipx install alibabacloud-sls-mcp-proxy

Or install it in the current Python environment:

python -m pip install alibabacloud-sls-mcp-proxy

Quick start

Use an Alibaba Cloud CLI profile

Configure a profile with Alibaba Cloud CLI, then start the proxy with its name:

uvx alibabacloud-sls-mcp-proxy@latest --profile default

stdio is the default transport. The proxy reads MCP JSON-RPC messages from stdin, writes responses to stdout, and sends logs to stderr.

The following MCP client configuration starts the proxy on demand:

{
  "mcpServers": {
    "alibabacloud-sls": {
      "command": "uvx",
      "args": [
        "alibabacloud-sls-mcp-proxy@latest",
        "--profile",
        "default"
      ]
    }
  }
}

If a desktop application cannot find uvx, replace uvx with its absolute path.

Use credentials from environment variables

Without --profile, provide both of these environment variables in the process that starts the proxy:

• ALIBABA_CLOUD_ACCESS_KEY_ID
• ALIBABA_CLOUD_ACCESS_KEY_SECRET

For temporary credentials, also provide ALIBABA_CLOUD_SECURITY_TOKEN. Then run:

uvx alibabacloud-sls-mcp-proxy@latest

Prefer a secret manager or the MCP client's environment configuration over putting credentials directly on a command line.

Use the local HTTP transport

To expose an MCP endpoint to another local process:

alibabacloud-sls-mcp-proxy \
  --profile default \
  --transport http \
  --port 8080 \
  --endpoint sls.aliyuncs.com

Connect the MCP client to http://127.0.0.1:8080/mcp. The listener always binds to the loopback interface and is not exposed to the network.

Credential selection

The proxy selects exactly one credential provider:

1. A non-empty --profile or ALIBABA_CLOUD_PROFILE selects an Alibaba Cloud CLI profile.
2. In profile mode, --sts-token or ALIBABA_CLOUD_SECURITY_TOKEN overrides the STS token read from the profile.
3. Without a profile, the proxy requires both the AccessKey ID and AccessKey secret from command-line options or environment variables.
4. The proxy does not silently fall back between profile and static credential modes.

When a profile contains an expiration time, the proxy asks Alibaba Cloud CLI to refresh temporary credentials shortly before they expire.

Command-line options

Option	Environment variable	Default	Description
--access-key-id	ALIBABA_CLOUD_ACCESS_KEY_ID	none	AccessKey ID used without a profile.
--access-key-secret	ALIBABA_CLOUD_ACCESS_KEY_SECRET	none	AccessKey secret used without a profile.
--profile	ALIBABA_CLOUD_PROFILE	none	Alibaba Cloud CLI profile. Takes precedence over static credentials.
--sts-token	ALIBABA_CLOUD_SECURITY_TOKEN	none	Optional STS token. Overrides the token from a profile.
--endpoint	MCP_UPSTREAM_ENDPOINT	sls.aliyuncs.com	SLS MCP endpoint. A host without a scheme uses HTTPS.
--transport	none	stdio	Local transport: stdio or http.
--port	MCP_PROXY_PORT	8080	Listen port for HTTP transport.
--headers KEY=VALUE	none	none	Extra upstream header; repeat the option to add more than one. Do not use it for credentials.
--timeout	none	120	Total request timeout in seconds.
--connect-timeout	none	10	Connection timeout in seconds.
--read-timeout	none	same as --timeout	Socket read timeout in seconds.
--retries	none	0	Number of retries after an upstream connection failure.
--log-level	none	info	debug, info, warning, or error.
--log-file	none	none	Also write logs to this local file.
--version	none	—	Print the installed version and exit.

Run alibabacloud-sls-mcp-proxy --help to see the options supported by the installed version.

Security notes

• Prefer an Alibaba Cloud CLI profile or environment variables over command-line credential options, which may be visible in shell history or the local process list.
• Remote endpoints must use HTTPS. Plain HTTP is accepted only for loopback addresses used in local testing.
• Redirects are not followed.
• Credentials and signed authorization values are not written to logs.
• The stdio transport reserves stdout for MCP protocol messages; logs are written to stderr.

Troubleshooting

--profile requires the aliyun CLI

: Install Alibaba Cloud CLI and make sure the aliyun executable is in the starting process's PATH.

aliyun configure get failed

: Check that the selected profile exists and contains usable credentials.

--access-key-id and --access-key-secret are required

: Supply both static credential environment variables, or select a configured profile with --profile.

Authentication errors from the endpoint

: Check that the credentials are active, an STS token has not expired, and the identity has permission to use the SLS MCP service.

Development

From the package directory:

uv sync
uv run python -m unittest -v
uv run python -m compileall -q src tests
./scripts/build.sh

To exercise the installed console entry point from the development environment:

uv run alibabacloud-sls-mcp-proxy --version

Publishing

The publish script rebuilds both distributions before upload. It publishes to TestPyPI by default:

./scripts/publish.sh

Set UV_PUBLISH_TOKEN to the API token for the target package index. TestPyPI and PyPI use separate tokens. The script requires this environment variable and never accepts or prints a token on the command line.

Pass pypi explicitly to publish to the production index:

./scripts/publish.sh pypi