Azure Blob Storage MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Azure Blob Storage. This server enables AI assistants like Claude to read, search, and explore files stored in Azure Blob Storage containers.

Features

• List Containers: View all blob containers in your Azure Storage Account
• List Blobs: Browse blobs within a container with optional prefix filtering
• Read Blob Content: Retrieve full content of text files with automatic truncation for large files
• Read Blob Chunks: Read specific portions of large files by byte range
• Search in Blob: Search for text within a specific blob file
• Search in Container: Search across all text files in a container
• Get Blob Metadata: Retrieve metadata and properties without downloading content

Requirements

• .NET 10.0 SDK
• Docker and Docker Compose (for local development with Azurite)
• Azure Storage Account (for production) or Azurite (for local development)

Quick Start

1. Clone and Build

git clone <repository-url>
cd mcp-azure-storage-account
dotnet build

2. Start Local Development Environment

docker-compose up -d

This starts:

• Azurite: Azure Storage emulator on ports 10000 (Blob), 10001 (Queue), 10002 (Table)
• MCP Server: Running on port 5001

3. Run the Server Locally

dotnet run --project src/Viamus.Azure.StorageAccount.Mcp.Server

The server will be available at:

• MCP Endpoint: http://localhost:5001/mcp
• Health Check: http://localhost:5001/health

Configuration

Environment Variables

Variable	Description	Required
AZURE_STORAGE_CONNECTION_STRING	Full connection string for Azure Storage	Yes*
AZURE_STORAGE_ACCOUNT_NAME	Storage account name (uses DefaultAzureCredential)	Yes*

*One of these must be provided.

Local Development (Azurite)

The default connection string for Azurite is pre-configured in launchSettings.json:

DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;

Production (Azure Storage Account)

Set the AZURE_STORAGE_CONNECTION_STRING environment variable with your Azure Storage connection string, or set AZURE_STORAGE_ACCOUNT_NAME to use Managed Identity/DefaultAzureCredential.

Available MCP Tools

list_containers

Lists all blob containers in the Azure Storage Account.

Returns: Array of containers with names and last modified dates.

list_blobs

Lists all blobs in a specific container.

Parameters:

• containerName (required): The name of the container
• prefix (optional): Filter blobs by prefix (e.g., logs/ for folder-like filtering)

Returns: Array of blobs with names, sizes, content types, and last modified dates.

get_blob_content

Gets the full content of a blob file.

Parameters:

• containerName (required): The name of the container
• blobName (required): The name/path of the blob
• maxCharacters (optional): Maximum characters to return (default: 100,000)

Returns: Blob content with metadata. Large files are automatically truncated.

get_blob_chunk

Gets a specific chunk/portion of a blob file.

Parameters:

• containerName (required): The name of the container
• blobName (required): The name/path of the blob
• startPosition (required): Starting byte position (0-based)
• length (required): Number of bytes to read

Returns: Chunk content with position information and remaining bytes.

search_in_blob

Searches for a specific term within a blob file.

Parameters:

• containerName (required): The name of the container
• blobName (required): The name/path of the blob
• searchTerm (required): The text to search for
• caseSensitive (optional): Case-sensitive search (default: false)
• maxResults (optional): Maximum results to return (default: 50)

Returns: Matching lines with line numbers.

search_in_container

Searches for a specific term across all text files in a container.

Parameters:

• containerName (required): The name of the container
• searchTerm (required): The text to search for
• blobPrefix (optional): Filter which blobs to search
• caseSensitive (optional): Case-sensitive search (default: false)
• maxResults (optional): Maximum results to return (default: 100)

Returns: Matching lines with blob names and line numbers.

get_blob_metadata

Gets detailed metadata and properties of a specific blob.

Parameters:

• containerName (required): The name of the container
• blobName (required): The name/path of the blob

Returns: Blob metadata including size, content type, and read recommendations.

Integrating with Claude Desktop

Step 1: Configure Claude Desktop

Add the MCP server to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "azure-blob-storage": {
      "url": "http://localhost:5001"
    }
  }
}

Step 2: Start the Server

Ensure the MCP server is running before starting Claude Desktop:

# Start Azurite (if using local development)
docker-compose up azurite -d

# Start the MCP server
dotnet run --project src/Viamus.Azure.StorageAccount.Mcp.Server

Step 3: Verify Connection

Open Claude Desktop and verify the connection by asking Claude to list your containers:

"List all containers in my Azure Storage account"

Creating a CLAUDE.md File for Context

To help Claude understand your specific blob storage structure and use cases, create a CLAUDE.md file in your project root. This file provides context about your data organization.

Example CLAUDE.md

# Azure Blob Storage Context

## Storage Structure

This Azure Blob Storage account contains the following containers:

### `logs`
Application logs organized by date and service:
- `logs/api/YYYY-MM-DD/*.log` - API server logs
- `logs/worker/YYYY-MM-DD/*.log` - Background worker logs
- `logs/errors/YYYY-MM-DD/*.json` - Error reports in JSON format

### `documents`
User-uploaded documents:
- `documents/{user-id}/` - User-specific files
- `documents/shared/` - Shared documents accessible to all users

### `backups`
Database backups:
- `backups/daily/YYYY-MM-DD.sql.gz` - Daily compressed SQL backups
- `backups/weekly/YYYY-WW.sql.gz` - Weekly backups

### `media`
Media files (images, videos):
- `media/images/{uuid}.{ext}` - Uploaded images
- `media/thumbnails/{uuid}.jpg` - Generated thumbnails

## Common Tasks

1. **Finding recent errors**: Search in `logs/errors/` for today's date
2. **User file lookup**: List blobs with prefix `documents/{user-id}/`
3. **Log analysis**: Search for specific error codes in `logs/api/`

## File Formats

- `.log` files are plain text, one entry per line
- `.json` files are structured JSON, can be searched directly
- `.sql.gz` files are compressed and cannot be read directly

## Naming Conventions

- Dates use ISO format: YYYY-MM-DD
- UUIDs are lowercase with hyphens
- All paths use forward slashes

Tips for Your CLAUDE.md

1. Document your folder structure: Explain how files are organized
2. Describe naming conventions: Help Claude understand patterns
3. List common tasks: Provide examples of frequent operations
4. Note file formats: Indicate which files are text-readable
5. Include search tips: Suggest effective search strategies

Running Tests

dotnet test

Project Structure

mcp-azure-storage-account/
├── src/
│   └── Viamus.Azure.StorageAccount.Mcp.Server/
│       ├── Program.cs                 # Application entry point
│       ├── Services/
│       │   ├── IAzureBlobStorageService.cs
│       │   └── AzureBlobStorageService.cs
│       └── Tools/
│           └── BlobStorageTools.cs    # MCP tool definitions
├── tests/
│   └── Viamus.Azure.StorageAccount.Mcp.Server.Tests/
│       ├── Services/
│       │   └── AzureBlobStorageServiceTests.cs
│       └── Tools/
│           └── BlobStorageToolsTests.cs
├── docker-compose.yml
├── README.md
└── CLAUDE.md                          # Your storage context file

Error Handling

All tools return structured JSON responses. When a resource is not found:

{
  "Error": "NotFound",
  "Message": "Blob 'file.txt' not found in container 'my-container'",
  "ResourceType": "Blob",
  "ResourceName": "file.txt",
  "ContainerName": "my-container"
}

For other errors:

{
  "Error": "ErrorCode",
  "Message": "Description of what failed",
  "Details": "Detailed error message",
  "StatusCode": 500
}

Docker Deployment

Build the Image

docker build -t azure-blob-mcp-server -f src/Viamus.Azure.StorageAccount.Mcp.Server/Dockerfile .

Run with Docker Compose

docker-compose up -d

Environment Variables for Docker

environment:
  - AZURE_STORAGE_CONNECTION_STRING=your-connection-string

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: dotnet test
5. Submit a pull request