ADLS2 MCP Server 🚀

1# ADLS2 MCP Server 🚀
2 
3A Model Context Protocol (MCP) server implementation for Azure Data Lake Storage Gen2. This service provides a standardized interface for interacting with ADLS2 storage, enabling file operations through MCP tools.
4 
5[![License](https://img.shields.io/github/license/erikhoward/adls-mcp-server)](https://opensource.org/licenses/MIT) [![Python Version](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/) [![uv](https://img.shields.io/badge/uv-package%20manager-blueviolet)](https://docs.astral.sh/uv/) [![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://github.com/modelcontextprotocol/spec)
6 
7## Setup 🛠️
8 
9### Installation 📦
10 
11Requires Python 3.13 or higher.
12 
13Install the package using `uv`:
14 
15```bash
16uv pip install adls2-mcp-server
17```
18 
19### MCP Configuration ⚙️
20 
21### Claude Desktop Configuration
22 
231 - Edit Claude Desktop Configuration:
24 
25Open `claude_desktop_config.json` and add the following configuration.
26 
27On MacOs, the file is located here:
28`~/Library/Application Support/Claude Desktop/claude_desktop_config.json`.
29 
30On Windows, the file is located here:
31`%APPDATA%\Claude Desktop\claude_desktop_config.json`.
32 
33```json
34{
35    "mcpServers": {
36        "adls2": {
37            "command": "adls2-mcp-server",
38            "env": {
39                "LOG_LEVEL": "DEBUG",
40                "UPLOAD_ROOT": "/path/to/store/uploads",
41                "DOWNLOAD_ROOT": "/path/to/store/downloads",
42                "AZURE_STORAGE_ACCOUNT_NAME": "your-azure-adls2-storage-account-name",
43                "READ_ONLY_MODE": "false"
44            }
45        }
46    }
47}
48```
49 
50The following is a table of available environment configuration variables:
51 
52| Variable | Description | Default |
53| --- | --- | --- |
54| `LOG_LEVEL` | Logging level | `INFO` |
55| `UPLOAD_ROOT` | Root directory for file uploads | `./uploads` |
56| `DOWNLOAD_ROOT` | Root directory for file downloads | `./downloads` |
57| `AZURE_STORAGE_ACCOUNT_NAME` | Azure ADLS2 storage account name | `None` |
58| `AZURE_STORAGE_ACCOUNT_KEY` | Azure ADLS2 storage account key (optional) | `None` |
59| `READ_ONLY_MODE` | Whether the server should operate in read-only mode | `true` |
60 
61 
62If `AZURE_STORAGE_ACCOUNT_KEY` is not set, the server will attempt to authenticate using Azure CLI credentials. Ensure you have logged in with Azure CLI before running the server:
63 
64```bash
65az login
66```
67 
682 - Restart Claude Desktop.
69 
70### Available Tools 🔧
71 
72#### Filesystem (container) Operations
73 
74- `list_filesystems` - List all filesystems in the storage account
75- `create_filesystem` - Create a new filesystem
76- `delete_filesystem` - Delete an existing filesystem
77 
78#### File Operations
79 
80- `upload_file` - Upload a file to ADLS2
81- `download_file` - Download a file from ADLS2
82- `file_exists` - Check if a file exists
83- `rename_file` - Rename/move a file
84- `get_file_properties` - Get file properties
85- `get_file_metadata` - Get file metadata
86- `set_file_metadata` - Set file metadata
87- `set_file_metadata_json` - Set multiple metadata key-value pairs using JSON
88 
89#### Directory Operations
90 
91- `create_directory` - Create a new directory
92- `delete_directory` - Delete a directory
93- `rename_directory` - Rename/move a directory
94- `directory_exists` - Check if a directory exists
95- `directory_get_paths` - Get all paths under the specified directory
96 
97## Development 💻
98 
99### Local Development Setup
100 
1011 - Clone the repository:
102 
103```bash
104git clone https://github.com/erikhoward/adls2-mcp-server.git
105cd adls2-mcp-server
106```
107 
1082 - Create and activate virtual environment:
109 
110Linux/macOS:
111 
112```bash
113python -m venv .venv
114source .venv/bin/activate
115```
116 
117Windows:
118 
119```bash
120.venv\Scripts\activate
121```
122 
1233 - Install dependencies:
124 
125```bash
126pip install -e ".[dev]"
127```
128 
1294 - Copy and configure environment variables:
130 
131```bash
132cp .env.example .env
133```
134 
135Edit .env with your settings.
136 
137```bash
138AZURE_STORAGE_ACCOUNT_NAME=your_azure_adls2_storage_account_name
139AZURE_STORAGE_ACCOUNT_KEY=your_azure_adls2_storage_key (optional)
140DOWNLOAD_ROOT=/path/to/download/folder
141UPLOAD_ROOT=/path/to/upload/folder
142READ_ONLY_MODE=True
143LOG_LEVEL=INFO
144```
145 
146If `AZURE_STORAGE_ACCOUNT_KEY` is not set, the server will attempt to authenticate using Azure CLI credentials. Ensure you have logged in with Azure CLI before running the server:
147 
148```bash
149az login
150```
151 
1525 - Claude Desktop Configuration
153 
154Open `claude_desktop_config.json` and add the following configuration.
155 
156On MacOs, the file is located here:
157`~/Library/Application Support/Claude Desktop/claude_desktop_config.json`.
158 
159On Windows, the file is located here:
160`%APPDATA%\Claude Desktop\claude_desktop_config.json`.
161 
162```json
163{
164    "mcpServers": {
165        "adls2": {
166            "command": "uv",
167            "args": [
168                "--directory",
169                "/path/to/adls2-mcp-server/repo",
170                "run",
171                "adls2-mcp-server"
172            ],
173            "env": {
174                "LOG_LEVEL": "DEBUG",
175                "UPLOAD_ROOT": "/path/to/store/uploads",
176                "DOWNLOAD_ROOT": "/path/to/store/downloads",
177                "AZURE_STORAGE_ACCOUNT_NAME": "your-azure-adls2-storage-account-name",
178                "READ_ONLY_MODE": "false"
179            }
180        }
181    }
182}
183```
184 
1856 - Restart Claude Desktop.
186 
187## Contributions 🤝
188 
189Contributions are welcome! Please feel free to submit a Pull Request.
190 
1911. Fork the repository
1922. Create your feature branch (`git checkout -b feature/AmazingFeature`)
1933. Commit your changes (`git commit -m '✨ Add some AmazingFeature'`)
1944. Push to the branch (`git push origin feature/AmazingFeature`)
1955. Open a Pull Request
196 
197## License ⚖️
198 
199Licensed under MIT - see [LICENSE.md](LICENSE) file.
200 
201**This is not an official Microsoft product.**
202