Ibm Flashsystems Mcpserver

IBM FlashSystem MCP Server

[](https://opensource.org/licenses/Apache-2.0) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io)

A Model Context Protocol (MCP) server that enables AI agents and LLMs to manage IBM FlashSystem storage systems through a standardised interface. This server bridges the gap between AI-powered automation and enterprise storage management, allowing intelligent agents to perform storage operations safely and efficiently.

🎯 Overview

The IBM FlashSystem MCP Server provides AI agents with the ability to:

• Manage Storage Volumes: Create, resize, rename, and organize volumes
• Configure Hosts: Set up Fibre Channel, iSCSI, and NVMe host connections
• Handle Snapshots: Create and manage volume and volume group snapshots
• Manage Volume Groups: Organize volumes with replication and snapshot policies
• Monitor Systems: Query system information and health status
• Control Partitions: View storage partitions

Built on the Model Context Protocol, this server enables seamless integration with MCP-compatible AI clients like Claude Desktop, allowing natural language interaction with IBM FlashSystem storage infrastructure.

📋 Table of Contents

• [Prerequisites](#-prerequisites)
• [Installation](#-installation)
• [Quick Start](#-quick-start)
• [Configuration](#-configuration)
• [Available Tools](#-available-tools)
• [Usage Examples](#-usage-examples)
• [Security](#-security)
• [Development](#-development)
• [Testing](#-testing)
• [Troubleshooting](#-troubleshooting)
• [Contributing](#-contributing)
• [License](#-license)
• [Support](#-support)

🔧 Prerequisites

• Python: 3.12 or higher
• IBM FlashSystem: Admin access to one or more IBM FlashSystem systems
• REST API Access: Valid credentials with appropriate permissions
• Network: HTTPS connectivity to FlashSystem management interface (default port 7443)

Supported IBM FlashSystem Code Level

• IBM Storage Virtualize version 9.1.0 and later

📦 Installation

Step 1: Clone the Repository

git clone https://github.com/IBM/ibm-flashsystems-mcpserver.git
cd ibm-flashsystems-mcpserver

Step 2: Choose Your Installation Method

Option A: Using pip (Global or Virtual Environment)

Use pip to install into your active Python environment (global Python or activated virtual environment):

# Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package in editable mode
pip install -e .

Option B: Using uv (Fast, Isolated Development)

Use uv for fast installations with automatic virtual environment management:

# uv automatically creates and manages a virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package in editable mode (faster than pip)
uv pip install -e .

Step 3: Verify Installation

If you used pip (Option A):

python -c "import flashsystem_mcp; print('Installation successful!')"

If you used uv (Option B):

# Option 1: With activated virtual environment
python -c "import flashsystem_mcp; print('Installation successful!')"

# Option 2: Using uv run (without activating venv)
uv run python -c "import flashsystem_mcp; print('Installation successful!')"

🚀 Quick Start

1. Create Configuration File

Create a configuration file mcp_server_config.json:

{
  "flashsystems": {
    "production-fs": {
      "name": "production-fs",
      "rest_base_url": "https://flashsystem.example.com:7443",
      "rest_username": "admin",
      "rest_password_file": "/secure/path/to/password_file",
      "verify_tls": true,
      "description": "Production FlashSystem"
    }
  },
  "default_flashsystem": "production-fs"
}

2. Create Secure Password File

# Create password file with secure permissions
echo "your_password_here" > /secure/path/to/password_file
chmod 600 /secure/path/to/password_file

Important: The password file must have owner-only read/write permissions (0600 or 0400 on Unix/Linux, restricted ACLs on Windows).

3. Start the Server

# Basic usage
python -m flashsystem_mcp_server mcp_server_config.json

# With custom log directory
python -m flashsystem_mcp_server mcp_server_config.json /path/to/logs

Command Line Arguments:

• Argument 1 (required): Path to configuration file
• Argument 2 (optional): Path to log directory (default: ./logs)

Logging: The server outputs structured JSON logs that can be easily ingested into monitoring and observability platforms:

• Format: JSON (one log entry per line)
• Location: Configurable log directory (default: ./logs/flashsystem_mcp_server.log)
• Integration: Compatible with Prometheus, Grafana Loki, ELK Stack, Splunk, and other log aggregation tools
• Fields: Includes timestamps (ISO 8601), log levels, correlation IDs, operation details, and execution metrics

Example Log Entry:

{
  "timestamp": "2026-01-15T10:30:45.123456Z",
  "level": "info",
  "event": "Tool execution completed",
  "correlation_id": "01HQXYZ123ABC",
  "tool_name": "lsvdisk",
  "execution_time": 0.234,
  "api_execution_time": 0.189,
  "transport": "rest",
  "rest_base_url": "https://flashsystem.example.com:7443",
  "result_count": 15,
  "success": true
}

4. Connect with an MCP Client

Claude Desktop Configuration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ibm-flashsystem": {
      "command": "python",
      "args": [
        "-m",
        "flashsystem_mcp_server",
        "/path/to/mcp_server_config.json",
        "/path/to/logs"
      ]
    }
  }
}

Note: The second argument (log directory) is optional. If omitted, logs will be written to ./logs in the current working directory.

⚙️ Configuration

Configuration File Structure

{
  "flashsystems": {
    "system-name": {
      "name": "system-name",
      "rest_base_url": "https://hostname:7443",
      "rest_username": "username",
      "rest_password_file": "/path/to/password_file",
      "verify_tls": true,
      "description": "Optional description"
    }
  },
  "default_flashsystem": "system-name"
}

Configuration Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | name | string | Yes | Unique identifier for the FlashSystem | | rest_base_url | string | Yes | Base URL (e.g., https://10.0.0.5:7443) | | rest_username | string | Yes | REST API username | | rest_password_file | string | Yes | Path to secure password file | | verify_tls | boolean | No | Enable TLS certificate verification (default: true) | | description | string | No | Human-readable description |

Environment Variables

You can override configuration using environment variables:

export FLASHSYSTEM_REST_BASE_URL="https://flashsystem.example.com:7443"
export FLASHSYSTEM_REST_USERNAME="admin"
export FLASHSYSTEM_REST_PASSWORD_FILE="/secure/path/to/password_file"

Multiple FlashSystems

Configure multiple systems for multi-site management:

{
  "flashsystems": {
    "site-a": {
      "name": "site-a",
      "rest_base_url": "https://site-a.example.com:7443",
      "rest_username": "admin",
      "rest_password_file": "/secure/site-a-password",
      "verify_tls": true
    },
    "site-b": {
      "name": "site-b",
      "rest_base_url": "https://site-b.example.com:7443",
      "rest_username": "admin",
      "rest_password_file": "/secure/site-b-password",
      "verify_tls": true
    }
  },
  "default_flashsystem": "site-a"
}

🛠️ Available Tools

The server exposes 20+ MCP tools for storage management:

Volume Management

| Tool | Description | |------|-------------| | ibm_flashsystem_list_volumes | List all volumes or get details of a specific volume | | ibm_flashsystem_create_volume | Create a new volume with specified size and pool | | ibm_flashsystem_rename_volume | Change the name of an existing volume | | ibm_flashsystem_resize_volume | Expand or shrink a volume | | ibm_flashsystem_change_volume_volumegroup | Move a volume to a different volume group | | ibm_flashsystem_list_storage_pools | List available storage pools (mdisk groups) |

Host Management

| Tool | Description | |------|-------------| | ibm_flashsystem_list_hosts | List all hosts or get details of a specific host | | ibm_flashsystem_create_host_fc | Create a Fibre Channel host | | ibm_flashsystem_create_host_iscsi | Create an iSCSI host | | ibm_flashsystem_create_host_nvme | Create an NVMe host | | ibm_flashsystem_map_volume_to_host | Map a volume to a host for access | | ibm_flashsystem_modify_host | Modify host properties | | ibm_flashsystem_list_portsets | List available portsets |

Host Cluster Management

| Tool | Description | |------|-------------| | ibm_flashsystem_create_host_cluster | Create a host cluster for high availability | | ibm_flashsystem_list_host_clusters | List all host clusters | | ibm_flashsystem_add_host_to_cluster | Add a host to an existing cluster | | ibm_flashsystem_map_volume_to_host_cluster | Map a volume to a host cluster |

Volume Group Management

| Tool | Description | |------|-------------| | ibm_flashsystem_create_volume_group | Create a new volume group | | ibm_flashsystem_list_volume_groups | List all volume groups | | ibm_flashsystem_rename_volume_group | Rename a volume group | | ibm_flashsystem_modify_volumegroup_replication_policy | Change replication policy | | ibm_flashsystem_modify_volumegroup_snapshot_policy | Change snapshot policy |

Snapshot Management

| Tool | Description | |------|-------------| | ibm_flashsystem_create_snapshot | Create a snapshot of volumes or volume group | | ibm_flashsystem_list_volume_snapshots | List snapshots of a specific volume | | ibm_flashsystem_list_volumegroup_snapshots | List snapshots of a volume group | | ibm_flashsystem_list_snapshot_policies | List available snapshot policies |

System Management

| Tool | Description | |------|-------------| | ibm_flashsystem_get_system_info | Get system information and health status | | ibm_flashsystem_list_partitions | List storage partitions | | ibm_flashsystem_list_replication_policies | List replication policies |

💡 Usage Examples

Example 1: List All Volumes

User Request:

"List all volumes on the FlashSystem"

MCP Tool Call:

ibm_flashsystem_list_volumes

Request:

{
  "volume_name": null,
  "flashsystem_name": null
}

Response:

{
  "success": true,
  "data": [
    {
      "name": "volume1",
      "capacity": "100GB",
      "volume_group_name": "prod-vg"
    },
    {
      "name": "volume2",
      "capacity": "500GB",
      "volume_group_name": "dev-vg"
    }
  ],
  "error_message": null,
  "error_type": null
}

Example 2: Create a New Volume

User Request:

"Create a 200MB volume in mdg0 pool and add it to volumegroup1"

MCP Tool Call:

ibm_flashsystem_create_volume

Request:

{
  "pool": "mdg0",
  "size": 200,
  "unit": "mb",
  "volume_group": "volumegroup1"
}

Response:

{
  "success": true,
  "data": [
    {
      "id": "24",
      "message": "Volume created successfully"
    }
  ],
  "error_message": null,
  "error_type": null
}

Example 3: List Storage Pools

User Request:

"Show me all the volume pools"

MCP Tool Call:

ibm_flashsystem_list_storage_pools

Request:

{}

Response:

{
  "success": true,
  "data": [
    {
      "name": "mdg0",
      "free_capacity": "21.16TB"
    },
    {
      "name": "mdg0_child0",
      "free_capacity": "440.00GB"
    },
    {
      "name": "mdg0_child1",
      "free_capacity": "433.00GB"
    }
  ],
  "error_message": null,
  "error_type": null
}

Example 4: Create a Volume Group

User Request:

"Make me a volume group in myPartition"

MCP Tool Call:

ibm_flashsystem_create_volume_group

Request:

{
  "partition": "myPartition"
}

Response:

{
  "success": true,
  "data": [
    {
      "id": "12",
      "message": "Volume group created successfully"
    }
  ],
  "error_message": null,
  "error_type": null
}

Example 5: Multi-System Management

User Request:

"List volumes on site-b FlashSystem"

MCP Tool Call:

ibm_flashsystem_list_volumes

Request:

{
  "volume_name": null,
  "flashsystem_name": "site-b"
}

Response:

{
  "success": true,
  "data": [
    {
      "name": "site-b-vol1",
      "capacity": "1TB",
      "volume_group_name": "backup-vg"
    }
  ],
  "error_message": null,
  "error_type": null
}

🔒 Security

Password File Security

The server enforces strict security requirements for password files:

Unix/Linux/macOS:

• File must have permissions 0600 (owner read/write only) or 0400 (owner read only)
• No group or other permissions allowed

Windows:

• File must have ACLs restricting access to owner and trusted system accounts only
• No access for other users or groups

TLS/SSL Configuration

Always use TLS verification in production:

{
  "verify_tls": true
}

For development/testing with self-signed certificates:

{
  "verify_tls": false
}

🔨 Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/IBM/ibm-flashsystems-mcpserver.git
cd ibm-flashsystems-mcpserver

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

Project Structure

ibm-flashsystems-mcpserver/
├── src/
│   ├── flashsystem_mcp/          # Main MCP server implementation
│   │   ├── server.py             # Server initialization
│   │   ├── config.py             # Configuration management
│   │   ├── executor.py           # Tool execution logic
│   │   ├── client_factory.py     # FlashSystem client factory
│   │   └── tools/                # MCP tool implementations
│   ├── flashrest/                # REST API client
│   │   ├── client.py             # HTTP client
│   │   ├── endpoints.py          # API endpoints
│   │   └── api_result.py         # Result types
│   ├── fs_core/                  # Core types and utilities
│   │   ├── fs_requests.py        # Request models
│   │   ├── fs_responses.py       # Response models
│   │   └── fs_types.py           # Type definitions
│   └── config_models.py          # Configuration models
├── tests/                        # Test suite
├── pyproject.toml               # Project metadata and dependencies
└── README.md                    # This file

Code Quality Tools

# Format code
ruff format .

# Lint code
ruff check .

# Type checking
mypy src/

# Run all checks
ruff check . && ruff format --check . && mypy src/

🧪 Testing

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_mcp_tools/test_volume_tools.py

# Run with verbose output
pytest -v

# Run and stop on first failure
pytest -x

Test Structure

• tests/test_mcp_tools/ - MCP tool integration tests
• tests/test_client_endpoints/ - REST API endpoint tests
• tests/test_configuration/ - Configuration validation tests
• tests/test_security/ - Security and permission tests

🐛 Troubleshooting

Debug Logging

Enable debug logging for troubleshooting:

import logging
logging.basicConfig(level=logging.DEBUG)

Or set environment variable:

export L

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [IBM](https://github.com/IBM)
- **Source:** [IBM/ibm-flashsystems-mcpserver](https://github.com/IBM/ibm-flashsystems-mcpserver)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.