Metadata-Version: 2.4
Name: alibabacloud-tair-openapi-mcp-server
Version: 0.0.1
Summary: MCP server for managing Alibaba Cloud R-KVStore (Tair/Redis) via OpenAPI
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: python-dotenv>=1.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: alibabacloud_tea_openapi>=0.3.8
Requires-Dist: alibabacloud_r_kvstore20150101==6.1.0
Requires-Dist: alibabacloud_vpc20160428>=3.0.0

<p align="center">English | <a href="./README_CN.md">中文</a><br></p>
# Alibaba Cloud Tair OpenAPI MCP Server

[![PyPI version](https://badge.fury.io/py/alibabacloud-tair-openapi-mcp-server.svg)](https://badge.fury.io/py/alibabacloud-tair-openapi-mcp-server)
[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

MCP server for managing Alibaba Cloud R-KVStore (Tair/Redis) via OpenAPI

## Prerequisites
1. Python >=3.12
2. Alibaba Cloud credentials with access to Alibaba Cloud R-KVStore services
3. [Cline](https://github.com/eline-pm/eline) MCP client (recommended) or other MCP-compatible client

## Installation

### Option 1: Install from PyPI
```bash
pip install alibabacloud-tair-openapi-mcp-server
```

### Option 2: Install from Source with UV
```bash
# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install
git clone https://github.com/aliyun/alibabacloud-tair-mcp-server.git
cd alibabacloud-tair-mcp-server/tair_openapi_mcp_server
uv venv
source .venv/bin/activate
uv pip install -e .
```

## Quick Start

### Setup with Cline (Recommended)

1. **Install the server** (using PyPI or UV as shown above)

2. **Configure Cline** by adding this to your Cline configuration:

```json
{
  "mcpServers": {
    "tair-openapi": {
      "command": "tair-openapi-mcp-server",
      "args": [],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "your-access-key-id",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "your-access-key-secret"
      }
    }
  }
}
```

Replace the credentials with your actual Alibaba Cloud access keys.

### Alternative: Claude Desktop Setup

For Claude Desktop, add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tair-openapi": {
      "command": "tair-openapi-mcp-server",
      "args": [],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "your-access-key-id",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "your-access-key-secret"
      }
    }
  }
}
```

## Features

This MCP server provides comprehensive access to Alibaba Cloud R-KVStore (Tair/Redis) services including:

### Core Instance Operations
- **Instance Management**: Create Redis Community Edition and Tair Enterprise Edition instances (classic and cloud-native)
- **Resource Discovery**: Query available regions, zones, and instance specifications
- **Network Configuration**: VPC and VSwitch management for instance deployment

### Account Management
- **Account Operations**: Query and manage database accounts
- **Password Management**: Reset account passwords with security validation

### Security Management
- **IP Whitelist**: Configure and manage IP whitelist groups for access control
- **Security Groups**: Query and modify security IP groups

### Multi-language Support
- Full Chinese and English language support for all operations

## Available OpenAPI Tools

This server provides the following Tair/Redis management tools:

### Resource Discovery
* `describe_regions`: List all available regions for Alibaba Cloud Tair instances
* `describe_zones`: Query available zones in a region for Tair instances
* `describe_available_resource`: Query available instance specifications in a specific zone
* `describe_vpcs`: Query VPC (Virtual Private Cloud) list in a region
* `describe_vswitches`: Query VSwitch (Virtual Switch) list in a region

### Instance Management
* `create_instance`: Create a Redis Community Edition or Tair Enterprise Edition Classic instance
  - Supports both classic and cloud-native deployment types
  - Automatic DryRun pre-check before creation
  - Supports master-slave and cluster configurations
* `create_tair_instance`: Create a Tair Enterprise Edition cloud-native instance
  - Supports MASTER_SLAVE and STAND_ALONE shard types
  - Flexible shard count configuration (1-128)
  - Automatic DryRun pre-check before creation

### Account Management
* `describe_accounts`: Query account information for a Tair instance
* `reset_account_password`: Reset the password for a Tair account with security validation

### Security Management
* `describe_security_ips`: Query IP whitelist configuration for a Tair instance
* `modify_security_ips`: Modify IP whitelist for a Tair instance
  - Supports Cover, Append, and Delete modes
  - Supports CIDR notation and single IP addresses
  - Maximum 1000 IP entries per group

## Configuration Options

### Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `ALIBABA_CLOUD_ACCESS_KEY_ID` | Alibaba Cloud Access Key ID | - | Yes |
| `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | Alibaba Cloud Access Key Secret | - | Yes |
| `TAIR_MCP_LOG_LEVEL` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | `INFO` | No |
| `TAIR_MCP_LOG_FILE` | Optional log file path | - | No |

### Permissions

Ensure your Alibaba Cloud credentials have the following permissions:
- R-KVStore (Tair/Redis) read/write access
- VPC read access for network configuration
- Account management permissions

## Development

### Local Development Setup
```bash
git clone https://github.com/aliyun/alibabacloud-tair-mcp-server.git
cd alibabacloud-tair-mcp-server/tair_openapi_mcp_server

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install
uv venv
source .venv/bin/activate
uv pip install -e .

# Run tests (if available)
pytest test/
```

### Building from Source
```bash
uv build
uv publish  # For maintainers only
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Support

- **Documentation**: [Alibaba Cloud Tair Documentation](https://www.alibabacloud.com/help/en/redis)
- **Issues**: Report issues on [GitHub](https://github.com/aliyun/alibabacloud-tair-mcp-server/issues)
- **MCP Protocol**: [Model Context Protocol](https://modelcontextprotocol.io)

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](../LICENSE) file for details.
