# EBS Initialization MCP Server
A Model Context Protocol (MCP) server for automating AWS EBS volume initialization. This server provides tools to initialize EBS volumes attached to EC2 instances using AWS Systems Manager.
## Features
- 🔍 **Volume Discovery**: Automatically discover all EBS volumes attached to an EC2 instance
- 🚀 **Automated Initialization**: Initialize volumes using `fio` (recommended) or `dd`
- ⏱️ **Smart Time Estimation**: Predict completion time based on volume size and throughput
- 📊 **Real-time Progress Tracking**: Visual progress bars with accurate percentage and remaining time
- ❌ **Cancellation Support**: Cancel ongoing initialization with complete process cleanup
- 🤖 **AI Agent Optimized**: Text-based responses optimized for AI agent compatibility
- 🌐 **Multi-Region Support**: Works across all AWS regions
- 🔒 **Secure Execution**: Uses AWS Systems Manager for secure remote execution
- 🏗️ **Modular Architecture**: Clean, maintainable codebase with separated concerns
## Installation
### Using uvx (Recommended)
```bash
# Run directly without installation (latest version)
uvx ebs-initializer-mcp@latest
# Or run specific version
uvx ebs-initializer-mcp==0.7.10
# Install globally
uv tool install ebs-initializer-mcp
# Upgrade to latest version
uvx --upgrade ebs-initializer-mcp
```
### From GitHub
```bash
uvx --from git+https://github.com/username/ebs-init-mcp.git ebs-mcp-server
```
## Usage
### As MCP Server
Add to your MCP configuration (`mcp_config.json`):
```json
{
"mcpServers": {
"ebs-initializer": {
"command": "uvx",
"args": ["ebs-initializer-mcp@latest"],
"env": {
"AWS_REGION": "us-west-2"
}
}
}
}
```
### Available Tools
1. **get_instance_volumes**: Get all EBS volumes attached to an instance
2. **initialize_all_volumes**: Initialize all volumes on an instance (parallel processing with time estimation)
3. **initialize_volume_by_id**: Initialize a specific volume by its volume ID
4. **check_initialization_status**: Monitor initialization progress and view detailed logs
5. **cancel_initialization**: Cancel ongoing initialization with complete process cleanup
### Example Usage with Claude Code
```
"Initialize all EBS volumes for instance i-1234567890abcdef0 using fio"
"Initialize volume vol-1234567890abcdef0 using fio"
"Check the status of the newly attached volume vol-abcdef1234567890"
"Cancel the initialization command 12345678-1234-1234-1234-123456789012"
```
The MCP server will:
1. Discover all attached EBS volumes and calculate estimated completion time
2. Install fio on the target instance
3. Run initialization commands in parallel with real-time throughput optimization
4. Provide **real-time progress tracking** with visual progress bars and accurate percentages
5. Return **AI agent-optimized flat JSON structure** for better compatibility
6. Allow cancellation with complete process cleanup if needed
## Progress Tracking
Version 0.6.7 introduces enhanced progress tracking optimized for AI agents:
### Visual Progress Display
- **Real-time progress bars**: `[██████████░░░░░░░░░░] 50.0%`
- **Accurate percentages**: Based on initial time estimation and elapsed time
- **Remaining time calculation**: Precise estimates of completion time
### AI Agent Optimization
- **Flat JSON structure**: Progress information at top-level fields for easy access
- **Priority field ordering**: Most important progress data comes first
- **Simple message format**: `"🔄 50.0% Complete..."`
### Response Structure
```json
{
"command_id": "...",
"status": "InProgress",
"execution_start_time": "2025-09-10 01:18:21.418000+00:00",
"progress_percentage": 50.0,
"progress_bar": "[██████████░░░░░░░░░░] 50.0%",
"estimated_remaining_minutes": 5.2,
"message": "🔄 50.0% Complete..."
}
```
## Prerequisites
- AWS CLI configured with appropriate permissions
- EC2 instances must have Systems Manager agent installed
- **Supported Operating Systems:**
- Amazon Linux 2
- Amazon Linux 2023
- Red Hat Enterprise Linux (RHEL)
- Ubuntu (18.04, 20.04, 22.04, 24.04)
- SUSE Linux Enterprise Server (SLES)
- Required IAM permissions:
- `ec2:DescribeVolumes`
- `ssm:SendCommand`
- `ssm:GetCommandInvocation`
## AWS IAM Permissions
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeVolumes",
"ssm:SendCommand",
"ssm:GetCommandInvocation"
],
"Resource": "*"
}
]
}
```
## Configuration
### Environment Variables
The server automatically detects AWS region from environment variables:
```bash
# Option 1: AWS_DEFAULT_REGION (preferred)
export AWS_DEFAULT_REGION=ap-northeast-2
# Option 2: AWS_REGION (also supported)
export AWS_REGION=ap-northeast-2
```
**Priority order:**
1. `AWS_DEFAULT_REGION` environment variable
2. `AWS_REGION` environment variable
3. Fallback to `us-east-1`
### MCP Configuration
```json
{
"mcpServers": {
"ebs-initializer": {
"command": "uvx",
"args": ["ebs-initializer-mcp@latest"],
"env": {
"AWS_DEFAULT_REGION": "ap-northeast-2"
}
}
}
}
```
## Architecture
### Modular Design
The codebase is organized into focused modules for maintainability and reusability:
```
src/ebs_init_mcp/
├── server.py # MCP server and tool definitions (430 lines)
├── aws_clients.py # AWS client caching and management
├── throughput.py # EBS throughput calculation
├── estimation.py # Time estimation algorithms
├── initialization.py # Command generation for volume initialization
├── status.py # Status checking and progress calculation
└── utils.py # Utility functions and device mapping scripts
```
### Time Estimation Logic
#### 1. `initialize_all_volumes` (Parallel Initialization)
**Algorithm**: Simulates parallel processing with throughput sharing
```python
# Step 1: Get instance EBS throughput
instance_throughput = get_instance_ebs_throughput(instance_type)
# Step 2: Collect volume data
volumes = [{'size_gb': size, 'max_throughput_mbps': vol_throughput}...]
# Step 3: AWS EBS throughput allocation algorithm
while volumes_remaining:
total_demand = sum(vol_throughput for each volume)
if total_demand <= instance_throughput:
# Each volume gets its maximum throughput
allocated_throughputs = [vol_max_throughput for each volume]
else:
# AWS EBS allocation: smaller volumes get priority
fair_share = instance_throughput / len(volumes_remaining)
# First pass: allocate full throughput to volumes <= fair_share
for volume in volumes_remaining:
if volume.max_throughput <= fair_share:
volume.allocated = volume.max_throughput
remaining_throughput -= volume.max_throughput
# Second pass: distribute remaining among larger volumes
remaining_large_volumes = volumes with throughput > fair_share
throughput_per_large = remaining_throughput / len(remaining_large_volumes)
for volume in remaining_large_volumes:
volume.allocated = throughput_per_large
# Calculate completion times and process next step
completion_times = [(size * 1024) / allocated_throughput / 60 for each volume]
```
**Example**: t3.large (500MB/s) with 3 volumes:
- Volume 1: 100GB/125MB/s, Volume 2: 100GB/1000MB/s, Volume 3: 100GB/1000MB/s
- Total demand: 2125MB/s > 500MB/s (exceeds instance limit)
- Allocation: Vol1=125MB/s, Vol2=187.5MB/s, Vol3=187.5MB/s
- Result: Vol2&3 finish at 9.1min, Vol1 continues alone → 13.7min total
#### 2. `initialize_volume_by_id` (Single Volume)
**Algorithm**: Simple throughput-limited calculation
```python
# Step 1: Get throughput constraints
instance_throughput = get_instance_ebs_throughput(instance_type)
volume_throughput = volume.get('Throughput', 1000)
# Step 2: Calculate effective throughput (bottleneck)
effective_throughput = min(volume_throughput, instance_throughput)
# Step 3: Linear time calculation
estimated_minutes = (size_gb * 1024 MB) / effective_throughput / 60
```
**Example**: 100GB volume, t3.large (500MB/s), gp3 (1000MB/s)
- Effective: min(1000, 500) = 500MB/s
- Time: (100 × 1024) / 500 / 60 = **3.4 minutes**
## Development
```bash
git clone <repository>
cd ebs-init-mcp
# Install dependencies
uv sync
# Run development server
AWS_REGION=ap-northeast-2 uv run mcp dev src/ebs_init_mcp/server.py
# Run tests
uv run pytest
# Format code
uv run ruff format src/
uv run ruff check src/
```
## License
MIT License
Raw data
{
"_id": null,
"home_page": null,
"name": "ebs-initializer-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "aws, ebs, fastmcp, initialization, mcp, volume",
"author": null,
"author_email": "sangkyuu <jsk6387@naver.com>",
"download_url": "https://files.pythonhosted.org/packages/10/e4/8e26a8840df5cc929258c7cba4cc9365f750ca0b92044810b76459cb7387/ebs_initializer_mcp-0.7.12.tar.gz",
"platform": null,
"description": "# EBS Initialization MCP Server\n\nA Model Context Protocol (MCP) server for automating AWS EBS volume initialization. This server provides tools to initialize EBS volumes attached to EC2 instances using AWS Systems Manager.\n\n## Features\n\n- \ud83d\udd0d **Volume Discovery**: Automatically discover all EBS volumes attached to an EC2 instance\n- \ud83d\ude80 **Automated Initialization**: Initialize volumes using `fio` (recommended) or `dd`\n- \u23f1\ufe0f **Smart Time Estimation**: Predict completion time based on volume size and throughput\n- \ud83d\udcca **Real-time Progress Tracking**: Visual progress bars with accurate percentage and remaining time\n- \u274c **Cancellation Support**: Cancel ongoing initialization with complete process cleanup\n- \ud83e\udd16 **AI Agent Optimized**: Text-based responses optimized for AI agent compatibility\n- \ud83c\udf10 **Multi-Region Support**: Works across all AWS regions\n- \ud83d\udd12 **Secure Execution**: Uses AWS Systems Manager for secure remote execution\n- \ud83c\udfd7\ufe0f **Modular Architecture**: Clean, maintainable codebase with separated concerns\n\n## Installation\n\n### Using uvx (Recommended)\n\n```bash\n# Run directly without installation (latest version)\nuvx ebs-initializer-mcp@latest\n\n# Or run specific version\nuvx ebs-initializer-mcp==0.7.10\n\n# Install globally\nuv tool install ebs-initializer-mcp\n\n# Upgrade to latest version\nuvx --upgrade ebs-initializer-mcp\n```\n\n### From GitHub\n\n```bash\nuvx --from git+https://github.com/username/ebs-init-mcp.git ebs-mcp-server\n```\n\n## Usage\n\n### As MCP Server\n\nAdd to your MCP configuration (`mcp_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"ebs-initializer\": {\n \"command\": \"uvx\",\n \"args\": [\"ebs-initializer-mcp@latest\"],\n \"env\": {\n \"AWS_REGION\": \"us-west-2\"\n }\n }\n }\n}\n```\n\n### Available Tools\n\n1. **get_instance_volumes**: Get all EBS volumes attached to an instance\n2. **initialize_all_volumes**: Initialize all volumes on an instance (parallel processing with time estimation)\n3. **initialize_volume_by_id**: Initialize a specific volume by its volume ID\n4. **check_initialization_status**: Monitor initialization progress and view detailed logs\n5. **cancel_initialization**: Cancel ongoing initialization with complete process cleanup\n\n### Example Usage with Claude Code\n\n```\n\"Initialize all EBS volumes for instance i-1234567890abcdef0 using fio\"\n\"Initialize volume vol-1234567890abcdef0 using fio\"\n\"Check the status of the newly attached volume vol-abcdef1234567890\"\n\"Cancel the initialization command 12345678-1234-1234-1234-123456789012\"\n```\n\nThe MCP server will:\n1. Discover all attached EBS volumes and calculate estimated completion time\n2. Install fio on the target instance\n3. Run initialization commands in parallel with real-time throughput optimization\n4. Provide **real-time progress tracking** with visual progress bars and accurate percentages\n5. Return **AI agent-optimized flat JSON structure** for better compatibility\n6. Allow cancellation with complete process cleanup if needed\n\n## Progress Tracking\n\nVersion 0.6.7 introduces enhanced progress tracking optimized for AI agents:\n\n### Visual Progress Display\n- **Real-time progress bars**: `[\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591] 50.0%`\n- **Accurate percentages**: Based on initial time estimation and elapsed time\n- **Remaining time calculation**: Precise estimates of completion time\n\n### AI Agent Optimization\n- **Flat JSON structure**: Progress information at top-level fields for easy access\n- **Priority field ordering**: Most important progress data comes first\n- **Simple message format**: `\"\ud83d\udd04 50.0% Complete...\"`\n\n### Response Structure\n```json\n{\n \"command_id\": \"...\",\n \"status\": \"InProgress\",\n \"execution_start_time\": \"2025-09-10 01:18:21.418000+00:00\",\n \"progress_percentage\": 50.0,\n \"progress_bar\": \"[\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591] 50.0%\",\n \"estimated_remaining_minutes\": 5.2,\n \"message\": \"\ud83d\udd04 50.0% Complete...\"\n}\n```\n\n## Prerequisites\n\n- AWS CLI configured with appropriate permissions\n- EC2 instances must have Systems Manager agent installed\n- **Supported Operating Systems:**\n - Amazon Linux 2\n - Amazon Linux 2023\n - Red Hat Enterprise Linux (RHEL)\n - Ubuntu (18.04, 20.04, 22.04, 24.04)\n - SUSE Linux Enterprise Server (SLES)\n- Required IAM permissions:\n - `ec2:DescribeVolumes`\n - `ssm:SendCommand`\n - `ssm:GetCommandInvocation`\n\n## AWS IAM Permissions\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"ec2:DescribeVolumes\",\n \"ssm:SendCommand\",\n \"ssm:GetCommandInvocation\"\n ],\n \"Resource\": \"*\"\n }\n ]\n}\n```\n\n## Configuration\n\n### Environment Variables\n\nThe server automatically detects AWS region from environment variables:\n\n```bash\n# Option 1: AWS_DEFAULT_REGION (preferred)\nexport AWS_DEFAULT_REGION=ap-northeast-2\n\n# Option 2: AWS_REGION (also supported) \nexport AWS_REGION=ap-northeast-2\n```\n\n**Priority order:**\n1. `AWS_DEFAULT_REGION` environment variable\n2. `AWS_REGION` environment variable \n3. Fallback to `us-east-1`\n\n### MCP Configuration\n\n```json\n{\n \"mcpServers\": {\n \"ebs-initializer\": {\n \"command\": \"uvx\",\n \"args\": [\"ebs-initializer-mcp@latest\"],\n \"env\": {\n \"AWS_DEFAULT_REGION\": \"ap-northeast-2\"\n }\n }\n }\n}\n```\n\n## Architecture\n\n### Modular Design\n\nThe codebase is organized into focused modules for maintainability and reusability:\n\n```\nsrc/ebs_init_mcp/\n\u251c\u2500\u2500 server.py # MCP server and tool definitions (430 lines)\n\u251c\u2500\u2500 aws_clients.py # AWS client caching and management\n\u251c\u2500\u2500 throughput.py # EBS throughput calculation\n\u251c\u2500\u2500 estimation.py # Time estimation algorithms\n\u251c\u2500\u2500 initialization.py # Command generation for volume initialization\n\u251c\u2500\u2500 status.py # Status checking and progress calculation\n\u2514\u2500\u2500 utils.py # Utility functions and device mapping scripts\n```\n\n### Time Estimation Logic\n\n#### 1. `initialize_all_volumes` (Parallel Initialization)\n\n**Algorithm**: Simulates parallel processing with throughput sharing\n\n```python\n# Step 1: Get instance EBS throughput\ninstance_throughput = get_instance_ebs_throughput(instance_type)\n\n# Step 2: Collect volume data\nvolumes = [{'size_gb': size, 'max_throughput_mbps': vol_throughput}...]\n\n# Step 3: AWS EBS throughput allocation algorithm\nwhile volumes_remaining:\n total_demand = sum(vol_throughput for each volume)\n \n if total_demand <= instance_throughput:\n # Each volume gets its maximum throughput\n allocated_throughputs = [vol_max_throughput for each volume]\n else:\n # AWS EBS allocation: smaller volumes get priority\n fair_share = instance_throughput / len(volumes_remaining)\n \n # First pass: allocate full throughput to volumes <= fair_share\n for volume in volumes_remaining:\n if volume.max_throughput <= fair_share:\n volume.allocated = volume.max_throughput\n remaining_throughput -= volume.max_throughput\n \n # Second pass: distribute remaining among larger volumes\n remaining_large_volumes = volumes with throughput > fair_share\n throughput_per_large = remaining_throughput / len(remaining_large_volumes)\n for volume in remaining_large_volumes:\n volume.allocated = throughput_per_large\n \n # Calculate completion times and process next step\n completion_times = [(size * 1024) / allocated_throughput / 60 for each volume]\n```\n\n**Example**: t3.large (500MB/s) with 3 volumes:\n- Volume 1: 100GB/125MB/s, Volume 2: 100GB/1000MB/s, Volume 3: 100GB/1000MB/s \n- Total demand: 2125MB/s > 500MB/s (exceeds instance limit)\n- Allocation: Vol1=125MB/s, Vol2=187.5MB/s, Vol3=187.5MB/s\n- Result: Vol2&3 finish at 9.1min, Vol1 continues alone \u2192 13.7min total\n\n#### 2. `initialize_volume_by_id` (Single Volume)\n\n**Algorithm**: Simple throughput-limited calculation\n\n```python\n# Step 1: Get throughput constraints\ninstance_throughput = get_instance_ebs_throughput(instance_type)\nvolume_throughput = volume.get('Throughput', 1000)\n\n# Step 2: Calculate effective throughput (bottleneck)\neffective_throughput = min(volume_throughput, instance_throughput)\n\n# Step 3: Linear time calculation\nestimated_minutes = (size_gb * 1024 MB) / effective_throughput / 60\n```\n\n**Example**: 100GB volume, t3.large (500MB/s), gp3 (1000MB/s)\n- Effective: min(1000, 500) = 500MB/s\n- Time: (100 \u00d7 1024) / 500 / 60 = **3.4 minutes**\n\n\n## Development\n\n```bash\ngit clone <repository>\ncd ebs-init-mcp\n\n# Install dependencies\nuv sync\n\n# Run development server\nAWS_REGION=ap-northeast-2 uv run mcp dev src/ebs_init_mcp/server.py\n\n# Run tests\nuv run pytest\n\n# Format code\nuv run ruff format src/\nuv run ruff check src/\n```\n\n## License\n\nMIT License\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for AWS EBS volume initialization",
"version": "0.7.12",
"project_urls": {
"Bug Reports": "https://github.com/jsk6387/ebs_init_mcp/issues",
"Repository": "https://github.com/jsk6387/ebs_init_mcp"
},
"split_keywords": [
"aws",
" ebs",
" fastmcp",
" initialization",
" mcp",
" volume"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "62b0d8b3d5be6f439d11ca3d1cd12515a8c5193ccbacd4f47722d12384af8f5b",
"md5": "74bb0cce7296aec601469d96a0f24051",
"sha256": "81f4b1c9db06fad37ccb2f7a4ae732fa1666c2362f5179f9011fe86bdeda48fd"
},
"downloads": -1,
"filename": "ebs_initializer_mcp-0.7.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "74bb0cce7296aec601469d96a0f24051",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 30885,
"upload_time": "2025-09-10T14:36:35",
"upload_time_iso_8601": "2025-09-10T14:36:35.340545Z",
"url": "https://files.pythonhosted.org/packages/62/b0/d8b3d5be6f439d11ca3d1cd12515a8c5193ccbacd4f47722d12384af8f5b/ebs_initializer_mcp-0.7.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "10e48e26a8840df5cc929258c7cba4cc9365f750ca0b92044810b76459cb7387",
"md5": "e9dd75ff6727e415eb92ee5b879e165a",
"sha256": "ec716595c1ee05eb236505714f8398d23d83200665ee61816457e660b0f1f112"
},
"downloads": -1,
"filename": "ebs_initializer_mcp-0.7.12.tar.gz",
"has_sig": false,
"md5_digest": "e9dd75ff6727e415eb92ee5b879e165a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 64420,
"upload_time": "2025-09-10T14:36:36",
"upload_time_iso_8601": "2025-09-10T14:36:36.920708Z",
"url": "https://files.pythonhosted.org/packages/10/e4/8e26a8840df5cc929258c7cba4cc9365f750ca0b92044810b76459cb7387/ebs_initializer_mcp-0.7.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 14:36:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jsk6387",
"github_project": "ebs_init_mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ebs-initializer-mcp"
}
JSON
