Connect AI Clients to Cloud Storage Operations Using the Backblaze B2 MCP Server

The Backblaze B2 MCP Server connects Model Context Protocol (MCP)-compatible AI clients to Backblaze B2 Cloud Storage. It allows an AI agent to perform storage operations through a defined set of tools instead of requiring you to write individual API calls or complete each task in the Backblaze web console.

The server can help an agent list and manage buckets, upload and download files, create presigned URLs, manage application keys, configure lifecycle and Object Lock settings, and analyze storage usage. The server uses the existing B2 Native and S3-Compatible APIs; it does not introduce a new storage protocol or data path.

NOTE:

The Backblaze B2 MCP Server is the official Backblaze-maintained MCP server for Backblaze B2 Cloud Storage and is currently incubating in Backblaze Labs. It is published on npm as @backblaze-labs/b2-mcp and listed in the MCP Registry as io.github.backblaze-labs/b2-mcp.

Who Should Use the B2 MCP Server

The B2 MCP Server is intended for developers, technical operators, and platform teams that use MCP-compatible AI clients to build, test, or manage storage workflows.

For example, you can use the server to:

• Explore and manage a B2 account conversationally during development and testing.

• Allow an agent to create buckets and upload, download, copy, list, or delete files.

• Generate short-lived presigned URLs for direct file transfers.

• Apply lifecycle rules, retention settings, legal holds, and Object Lock configuration.

• Review storage growth, egress, large files, and unfinished multipart uploads.

• Incorporate B2 storage into a larger agent-driven workflow.

The server is client-agnostic. Local STDIO configurations are available for Claude Desktop, Cursor, Visual Studio Code, Cline, Windsurf, Zed, Continue, Goose, and other MCP-compatible clients.

You can also use a customer-hosted HTTP deployment with HTTP-capable MCP clients, including Claude.ai Custom Connectors. HTTP deployments require additional authentication and security configuration.

Why Use the B2 MCP Server

An AI model may know general information about B2, but that knowledge does not give it access to your account or ensure that it uses the current API correctly. The B2 MCP Server provides current tool schemas and a controlled connection to B2 so that an agent can perform authorized operations.

For local use, B2 credentials remain in the server environment rather than being supplied to the model as tool parameters. Application-key capabilities limit the operations that the server can expose. Credential handling for self-hosted HTTP deployments depends on the configured credential mode.

How the B2 MCP Server Works

For the recommended local configuration, the MCP client starts the B2 MCP Server as a subprocess on your computer using STDIO transport. The server reads a B2 application key from the client configuration and exposes the tools that the key is authorized to use.

When you ask the client to perform a B2 task:

1. The AI client interprets your request and selects an appropriate B2 MCP tool.

2. The B2 MCP Server validates the tool input and checks the configured security policy.

3. The server calls the applicable B2 Native or S3-Compatible API operation.

4. Backblaze B2 performs the operation within the capabilities and restrictions of the configured application key.

5. The server returns a structured, sanitized result to the client.

Your B2 application key remains in the server environment and is not passed to the model as a tool parameter. A read-only or bucket-restricted key therefore exposes fewer tools than a key with broader account access. Account features, transport, and security policy can also affect tool availability.

Available Tools

The B2 MCP Server provides 40 tools in three categories:

• B2 Native tools (17): Authorize an account; create, list, update, and delete buckets; manage bucket notification rules; manage application keys; configure file retention and legal holds; and perform supported Partner API group and account operations.

• S3-Compatible tools (19): Upload, download, copy, list, and delete objects; inspect object and bucket metadata; create and manage multipart uploads; create presigned URLs; and configure bucket lifecycle rules.

• Analytics tools (4): Analyze storage growth, identify egress leaders, locate the largest files in a bucket, and identify unfinished multipart uploads.

Tool names include 21 b2_* tools and 19 s3_* tools. The b2_* group includes both Native B2 operations and custom analytics tools.

Some tools have additional requirements. Partner API tools require Partner API access and the appropriate credential. Storage-growth and egress analytics require Usage Reports.

For the current tool list and availability requirements, see the generated tool profiles.

The repository defines the following tool profiles:

• full: 40 tools

• read-only: 20 tools

Your client may display fewer tools if the configured key does not have the required capabilities or if the active security policy prevents a tool from returning a durable secret.

MCP resources and prompts

For clients that support MCP resources, the server provides the following read-only resources:

• b2://server-config: Non-secret server configuration.

• b2://capabilities: The current B2 capability set and active tool profile.

• b2://bucket/{bucketName}: Capability-gated bucket metadata with notification webhook secrets redacted.

The server also supports optional workflow prompts. Set B2_ENABLE_MCP_PROMPTS=true to enable them. Prompts are disabled by default and provide workflow guidance only; they do not execute tools or approve destructive actions.

B2 Skills Pack

The repository includes an optional B2 Skills pack for clients that support Markdown-based skills. The MCP server provides the tools that perform B2 operations, while the Skills pack provides workflow guidance for using those tools.

The included skills cover:

• Backup and restore

• Least-privilege application keys

• Object Lock

• Lifecycle and cost management

• Migration

• Incident response

The Skills pack does not add tools, permissions, or server endpoints. It sequences existing tools and provides guidance for data movement and destructive operations.

For installation instructions, see the B2 Skills pack.

For clients that support local Markdown skills, install the skill directories from skills/. For Claude Code, place each skills/b2-*/ directory under ~/.claude/skills/. For Claude.ai or Claude Desktop, upload per-skill ZIP files through Settings > Capabilities > Skills.

Before You Begin

To run the B2 MCP Server locally, you need:

• A Backblaze B2 account.

• A dedicated B2 application key. A non-master application key is sufficient for standard B2 Native and S3-Compatible operations.

• Node.js 22.22.2 or later in the Node.js 22 release line, or Node.js 24 or 26. Backblaze CI and deployment guidance test Node.js 22.23.1, 24, and 26.

• An MCP-compatible client that supports local STDIO servers.

Create a key with only the capabilities, bucket access, file-name prefix, and duration required for the intended workflow. For instructions, see How to Create and Manage App Keys in Backblaze B2 Cloud Storage and Application Key Capabilities.

Important

Do not use your master application key for ordinary storage operations. Master credentials are required only for supported Partner API operations on an account that is authorized to use the Partner API.

If you need to specify a region before account authorization, add B2_REGION to the server environment, for example us-east-005. Otherwise, S3 and report tools derive the region from the authorized B2 account response.

Connect a Local MCP Client

The recommended setup uses the published @backblaze-labs/b2-mcp npm package over STDIO. The MCP client runs the package with npx; you do not need to clone or build the repository.

The following example configures Claude Desktop:

1. Open the Claude Desktop configuration file for your operating system:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the following server configuration. Replace the placeholder values with your application key ID and application key secret.

{
  "mcpServers": {
    "backblaze-b2": {
      "command": "npx",
      "args": ["-y", "@backblaze-labs/b2-mcp"],
      "env": {
        "B2_APPLICATION_KEY_ID": "your-application-key-id",
        "B2_APPLICATION_KEY": "your-application-key-secret"
      }
    }
  }
}

3. Save the configuration file and restart Claude Desktop.

4. Ask the client to perform a read-only operation, such as:

List the buckets this key can access.

If the connection is successful, the client displays the B2 tools available to the configured application key.

Other clients use the same command, arguments, and environment variables but store them in different configuration files. For client-specific examples, see Connecting MCP clients to the B2 MCP server.

Claude Desktop Extension Option

Claude Desktop users can also install the B2 MCP Server as an extension instead of editing the JSON configuration file manually.

Beginning with release v0.2.1, GitHub releases include a b2-mcp.mcpb extension bundle.

To install it:

1. Download b2-mcp.mcpb from the latest release.

2. In Claude Desktop, select Settings > Extensions > Advanced settings > Extension Developer > Install Extension....

3. Select the downloaded file.

4. Enter your Application Key ID and Application Key when prompted.

Region and master-key values are optional.

The npx STDIO configuration remains the recommended setup for clients other than Claude Desktop.

Security Considerations

Use the B2 MCP Server with the same care that you use for any application that can access or modify cloud storage.

• Create a dedicated, least-privilege application key for the server. Restrict the key to the necessary capabilities, buckets, file-name prefixes, and duration.

• Never commit application keys to a repository or include them in prompts, messages, logs, or screenshots.

• Review requested tool calls before approving them. Local STDIO operation requires confirmation for destructive, secret-producing, and protection-weakening actions by default.

• Treat presigned URLs as sensitive bearer credentials until they expire.

• Keep the MCP client, Node.js runtime, and B2 MCP package current.

• Review the repository security and authentication guidance before exposing the server through HTTP or allowing untrusted clients to connect.

On macOS and Linux, local STDIO operation writes one-time secrets created by supported key-management tools to ~/.b2-mcp/secrets.jsonl by default instead of returning them to the model. This file contains plaintext credentials. Protect it like any other active credential and rotate or delete its contents according to your credential-retention policy.

File-based secret output is disabled on Windows because the current implementation does not enforce owner-only access control lists.

For ordinary object transfers, use presigned URLs when possible. Inline s3_put_object requests and response-inline s3_get_object operations are limited to objects of 1 MiB or less.

During normal local or self-hosted operation, the publisher does not receive your runtime B2 credentials, object data, prompts, logs, or telemetry. For more information, see the repository privacy policy.

For additional security information, see Authentication and credential custody and Security and self-hosting.

Self-Hosting and Advanced Deployment

Local STDIO is the recommended starting point. The repository also provides Docker and customer-hosted HTTP deployment options for teams that need a remotely accessible MCP endpoint.

HTTP deployments require you to configure authentication, credential custody, TLS termination, allowed hosts and origins, rate limiting, and destructive-action policy. Do not expose a default local configuration directly to the internet.

Important: The standalone Node HTTP entry point does not authenticate callers by itself.

Hosted deployments support the following credential modes:

• headers: B2 credentials are supplied in HTTP headers for tool-execution requests.

• server: The server process or secret store holds a single customer-managed B2 credential.

• principal: An authenticated MCP principal maps to customer-managed B2 credentials.

For new hosted deployments, use server or principal mode when possible rather than sending B2 credentials with every request.

See the deployment guides and hosted security contract before deploying the server outside a trusted local environment.

Troubleshooting

The client shows fewer than 40 tools

The configured application key may not have all required capabilities, Partner API credentials may not be configured, or the active secret-handling policy may prevent a tool from producing a durable secret.

A tool returns missing_credentials

The server does not have usable B2 credentials for the requested operation. Configure the required environment variables or HTTP credential mode before executing the tool.

S3 or report operations use the wrong region before authorization

Add B2_REGION to the server environment.

npx cannot start the package

Verify that the MCP client can access npx and that you are using a supported Node.js runtime.

A newly generated application-key secret does not appear

Check the configured B2_SECRET_SINK. File sink mode requires a safe, owner-only file path on supported POSIX systems. HTTP and serverless deployments default to off.

Limitations

• You run and manage the server in your own environment; it is not a Backblaze-hosted MCP service.

• Available tools depend on the configured application key's capabilities, account features, transport, and security policy.

• Partner API tools require separate Partner API authorization and credentials.

• Usage-report analytics require Usage Reports to be enabled for the account.

• MCP client behavior, including confirmation prompts, can vary by client and supported MCP protocol version.

• HTTP deployments require a reviewed authentication boundary and hosted security configuration.

The repository documentation is the source of truth for the current tool list, client compatibility, configuration variables, advanced deployment options, and implementation-specific limitations. For the latest information, see the Backblaze B2 MCP Server repository.