# Backblaze B2 MCP Server

A local [MCP](https://modelcontextprotocol.io) server that exposes [Backblaze B2 Cloud Storage](https://www.backblaze.com/cloud-storage) to MCP clients (Claude Desktop, Claude Code, etc.) — via the native B2 API (`b2_*` tools, the full feature set) and a B2 S3-compatible tool set (`s3_*` tools, for interoperability).

This is an unofficial, community project. It is not affiliated with or endorsed by Backblaze.

Developed by **Muhammed Ehab**, for the dev community. 🤝

## Requirements

- Node.js ≥ 20
- A [Backblaze B2 account](https://www.backblaze.com/sign-up/cloud-storage) (a free tier is available) and an application key (see below)

## Installation

```bash
git clone https://github.com/muhammedehab35/backblaz_b2_mcp.git
cd backblaz_b2_mcp
npm install
npm run build
```

## Getting a Backblaze B2 application key

Each user of this server needs their **own** B2 application key — never share a key or commit one to source control.

1. Sign in to the [Backblaze B2 dashboard](https://secure.backblaze.com/user_signin.htm).
2. Go to **Account** → **App Keys**.
3. Click **Add a New Application Key**.
   - Give it a name.
   - For safety, restrict it to a single bucket if you can (rather than granting account-wide access), and only grant the capabilities you actually need (e.g. `listBuckets`, `readFiles`, `writeFiles`, `deleteFiles` for typical use).
4. Backblaze shows the `keyID` and `applicationKey` **once**, at creation time. Copy both immediately — the `applicationKey` cannot be retrieved again later.

## Configuration

Copy `.env.example` to `.env` and fill in your own credentials:

```bash
cp .env.example .env
```

| Variable | Required | Description |
|---|---|---|
| `B2_APPLICATION_KEY_ID` | Yes | Your B2 application key ID |
| `B2_APPLICATION_KEY` | Yes | Your B2 application key secret |
| `B2_LARGE_FILE_THRESHOLD_MB` | No (default `200`) | File size above which `b2_upload_file` automatically switches to B2's multipart large-file API |

## Configure in Claude Desktop / Claude Code

Add to your MCP client config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "backblaze-b2": {
      "command": "node",
      "args": ["/absolute/path/to/backblaze-b2-mcp/dist/server.js"],
      "env": {
        "B2_APPLICATION_KEY_ID": "your_key_id",
        "B2_APPLICATION_KEY": "your_application_key"
      }
    }
  }
}
```

Use an absolute path to `dist/server.js`. Restart your MCP client after editing its config.

## Available tools

**Native B2 (`b2_*`)**

| Tool | Description |
|---|---|
| `b2_get_account_info` | Account id, capabilities, estimated storage usage |
| `b2_list_buckets` | List buckets |
| `b2_create_bucket` | Create a bucket |
| `b2_update_bucket` | Update a bucket's type, lifecycle rules, or CORS rules |
| `b2_delete_bucket` | Permanently delete an empty bucket |
| `b2_list_files` | List current file versions in a bucket |
| `b2_list_file_versions` | List every version of every file in a bucket |
| `b2_get_file_info` | Get metadata for a file version |
| `b2_upload_file` | Upload a local file (auto multipart for large files) |
| `b2_download_file` | Download a file to a local path |
| `b2_delete_file_version` | Permanently delete one specific file version |
| `b2_copy_file` | Copy a file server-side, without re-uploading it |
| `b2_get_download_authorization` | Create a temporary token to download from a private bucket |
| `b2_get_presigned_download_url` | Build a ready-to-use temporary download URL |
| `b2_list_keys` | List application keys |
| `b2_create_key` | Create a new, optionally scoped, application key |
| `b2_delete_key` | Delete (revoke) an application key |

**S3-compatible (`s3_*`)** — a smaller interoperability subset:

| Tool | Description |
|---|---|
| `s3_list_buckets` | List buckets |
| `s3_list_objects` | List objects in a bucket |
| `s3_put_object` | Upload a local file as an object |
| `s3_get_object` | Download an object to a local path |
| `s3_delete_object` | Delete an object |
| `s3_create_presigned_url` | Create a presigned GET or PUT URL |

## Notes & caveats

- Backblaze does not expose a billing/invoices API, so `b2_get_account_info`'s usage figures are an estimate (capped at the first 1000 files per bucket) — check the B2 web dashboard for exact costs.
- On a bucket with the default "keep all versions" lifecycle, `s3_delete_object` (like a real S3 client's `DeleteObject`) only **hides** the object — it does not free the underlying storage or let you delete the bucket. Use `b2_delete_file_version` for a true, permanent delete, or configure bucket lifecycle rules to expire hidden versions automatically.
- `b2_delete_bucket`, `b2_delete_file_version`, `b2_delete_key`, and `s3_delete_object` are irreversible.

## Development

- `npm run dev` — run the server directly with `tsx`
- `npm test` — run the unit test suite (mocked network, no live B2 account required)
- `npm run build` — compile to `dist/`