ADLS Gen2 MCP Endpoint Implementation 🚀

This repository hosts the necessary software stack to expose Azure Data Lake Storage Gen2 functionality through the standardized Model Context Protocol (MCP). It acts as a bridge, translating abstract MCP calls into concrete Azure SDK operations for storage manipulation.

Configuration and Deployment 🛠️

Installation Procedure 📦

Requires a contemporary Python environment (version 3.13 or newer).

Install the requisite package utilizing the uv toolchain:

bash uv pip install adls2-mcp-server

MCP Interface Setup ⚙️

Integrating with Claude Desktop

1. Configuration Modification: Access and modify your local claude_desktop_config.json file. Append the subsequent configuration block to define the new storage endpoint:

   • macOS Path: ~/Library/Application Support/Claude Desktop/claude_desktop_config.json
   • Windows Path: %APPDATA%\Claude Desktop\claude_desktop_config.json

   { "mcpServers": { "adls2": { "command": "adls2-mcp-server", "env": { "LOG_LEVEL": "DEBUG", "UPLOAD_ROOT": "/path/to/store/uploads", "DOWNLOAD_ROOT": "/path/to/store/downloads", "AZURE_STORAGE_ACCOUNT_NAME": "your-azure-adls2-storage-account-name", "READ_ONLY_MODE": "false" } } } }

Environment Configuration Variables Reference Table:

Parameter	Purpose	Default Value
LOG_LEVEL	Verbosity setting for logging output	INFO
UPLOAD_ROOT	Local staging directory for inbound transfers	./uploads
DOWNLOAD_ROOT	Local target directory for outbound transfers	./downloads
AZURE_STORAGE_ACCOUNT_NAME	Identifier for the targeted Azure Storage resource	None
AZURE_STORAGE_ACCOUNT_KEY	Secret key for authentication (optional)	None
READ_ONLY_MODE	Constraint flag to prevent write operations	true

Authentication Note: If AZURE_STORAGE_ACCOUNT_KEY is omitted, the system defaults to leveraging established Azure CLI credentials. Verify successful authentication beforehand:

bash az login

2 - Execute a restart of the Claude Desktop application to load the new service definition.

Accessible Utility Functions 🔧

Filesystem (Container) Administration

• list_filesystems - Enumerate all available filesystems within the configured storage account.
• create_filesystem - Provision a new filesystem resource.
• delete_filesystem - Erase a specified existing filesystem.

Object (File) Manipulation

• upload_file - Initiate the transfer of a local file to ADLS2.
• download_file - Retrieve a file from ADLS2 to the local system.
• file_exists - Verification check for file presence.
• rename_file - Atomically relocate or rename a file object.
• get_file_properties - Retrieve standard system attributes of a file.
• get_file_metadata - Fetch custom metadata key/value pairs associated with a file.
• set_file_metadata - Update a single metadata attribute on a file.
• set_file_metadata_json - Bulk update multiple metadata attributes using a JSON structure.

Hierarchical (Directory) Management

• create_directory - Establish a new folder structure.
• delete_directory - Remove an existing directory and its contents.
• rename_directory - Relocate or rename a directory structure.
• directory_exists - Determine if a specified path as a directory exists.
• directory_get_paths - Recursively retrieve all contained paths beneath a given directory.

Local Development Workflow 💻

Initial Repository Setup

1 - Obtain the source code repository:

bash git clone https://github.com/erikhoward/adls2-mcp-server.git cd adls2-mcp-server

2 - Isolate environment and activate:

Unix-like Systems (Linux/macOS):

bash python -m venv .venv source .venv/bin/activate

Windows:

bash .venv\Scripts\activate

3 - Install development dependencies:

bash pip install -e ".[dev]"

4 - Configure local runtime variables:

bash cp .env.example .env

Modify .env with your specific connection details:

bash AZURE_STORAGE_ACCOUNT_NAME=your_azure_adls2_storage_account_name AZURE_STORAGE_ACCOUNT_KEY=your_azure_adls2_storage_key (optional) DOWNLOAD_ROOT=/path/to/download/folder UPLOAD_ROOT=/path/to/upload/folder READ_ONLY_MODE=True LOG_LEVEL=INFO

If AZURE_STORAGE_ACCOUNT_KEY is absent, Azure CLI authentication is attempted. Ensure prior successful execution of az login.

5 - Claude Desktop Integration Configuration

Update claude_desktop_config.json using the following structure, noting the uv run command pattern for development mode execution:

{ "mcpServers": { "adls2": { "command": "uv", "args": [ "--directory", "/path/to/adls2-mcp-server/repo", "run", "adls2-mcp-server" ], "env": { "LOG_LEVEL": "DEBUG", "UPLOAD_ROOT": "/path/to/store/uploads", "DOWNLOAD_ROOT": "/path/to/store/downloads", "AZURE_STORAGE_ACCOUNT_NAME": "your-azure-adls2-storage-account-name", "READ_ONLY_MODE": "false" } } } }

6 - Relaunch Claude Desktop.

Collaborative Efforts 🤝

We encourage community contributions! Please submit enhancements via Pull Requests.

1. Create a personal fork of the repository.
2. Establish a new feature branch (git checkout -b feature/DescriptiveFeatureName).
3. Commit your modifications (git commit -m 'feat: Incorporate new functionality').
4. Push the branch upstream (git push origin feature/DescriptiveFeatureName).
5. Submit a formal Pull Request.

Licensing Information ⚖️

This software is distributed under the terms of the MIT License; consult the [LICENSE.md] file for details.

Disclaimer: This software project is independently developed and is not affiliated with Microsoft Corporation.

WIKIPEDIA EXCERPT (Contextual Information): Google Cloud Platform (GCP) represents a comprehensive suite of utility computing services provided by Google, encompassing modular offerings across computation, persistent data storage, advanced data analysis, and machine learning capabilities, supported by integrated management tooling. This infrastructure operates on the identical foundational hardware utilized internally by Google for its public-facing products like Google Search, Gmail, and Google Docs (as detailed by Verma et al.). Enrollment necessitates the provision of banking or credit card credentials. Google Cloud Platform offers environments spanning Infrastructure as a Service (IaaS), Platform as a Service (PaaS), and serverless execution models. Google's initial foray into cloud computing was the announcement of App Engine in April 2008, designed for hosting and developing web applications within Google-managed data centers. General availability for this service was achieved in November 2011. Following this debut, Google progressively augmented the platform with numerous additional cloud services. Currently, Google Cloud encompasses the public cloud infrastructure (GCP), the Google Workspace suite (formerly G Suite), enterprise versions of ChromeOS and Android, and various APIs for enterprise mapping and machine learning. Since at least 2022, official Google communications standardized the nomenclature to "Google Cloud," which occasionally leads to ambiguity regarding the underlying GCP infrastructure component.