b2-mcp-server
This server provides an MCP-compatible interface for managing Backblaze B2 Cloud Storage, enabling AI clients to interact with buckets, files, and application keys through a set of nine controlled tools.
b2_list_buckets: List all accessible buckets with ID, name, and type.
b2_list_files: List current files in a bucket with optional prefix filtering and pagination (up to 1,000 files), with truncation indicators.
b2_upload_file: Upload a local file from a configured safe directory (B2_UPLOAD_ROOT) to a bucket; creates a new version if the file name exists.
b2_download_file: Download a B2 file to a configured safe local directory (B2_DOWNLOAD_ROOT) atomically; returns the local path and SHA-1 checksum without exposing file content.
b2_hide_file: Hide a file from listings without deleting its data (reversible).
b2_unhide_file: Restore a previously hidden file by removing its latest hide marker.
b2_delete_file_version: Permanently delete a specific file version using its exact file ID (not inferred from filename); requires audit logging and can archive the file locally first.
b2_bucket_usage: Calculate storage used per bucket (including old versions) against a configurable budget, flagging buckets that exceed a threshold.
b2_list_keys: List application keys, their capabilities, and restrictions without exposing secrets.
All tools enforce strict path containment for local operations (B2_UPLOAD_ROOT and B2_DOWNLOAD_ROOT), guarding against symlink traversal and arbitrary filesystem access. The server handles errors gracefully by returning structured results, supports least-privilege credentials (B2 application keys with restricted capabilities), and indicates when listings or usage reports are partial. Deletion is deliberate and traceable thanks to audit logging and optional local archiving.
Provides tools for interacting with Backblaze B2 Cloud Storage, enabling AI agents to manage buckets, upload and download files, hide/unhide files, delete file versions, report bucket usage against a budget, and list application keys.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@b2-mcp-server Check which buckets are over 80% of their budget?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
b2-mcp-server
An MCP server that exposes Backblaze B2 Cloud Storage as tools any MCP-compatible AI client can call. Manage B2 by talking to an assistant -- "which buckets are over 80% of their budget?", "upload this file", "delete that version" -- instead of writing SDK code or clicking through the web console.
Nine tools over stdio: list buckets, list files, upload, download, hide, unhide, delete a version, report bucket usage against a budget, and list application keys.
Built on @backblaze-labs/b2-sdk and the MCP TypeScript SDK.
Why it is shaped this way
The interesting part of an MCP server is not the API calls. It is what happens when a language model is the one calling them.
Local filesystem access denies by default. Upload reads only from
B2_UPLOAD_ROOT, download writes only toB2_DOWNLOAD_ROOT, and both are refused outright when the root is unset. Read and write roots are separate so they can be granted independently. Paths are resolved withrealpathbefore the containment check, so a symlink inside the root cannot point outside it, and containment istarget === root || target.startsWith(root + sep)-- a barestartsWithwould admit the sibling directory/data/uploads-evilfor the root/data/uploads. Rejection messages name the offending path and never the root.The one tool that destroys data cannot be aimed loosely.
b2_delete_file_versiontakes an exactfileIdand refuses to resolve one from a file name, so "delete hello.txt" cannot be satisfied in a single step: the id has to come out of a listing a human can see. A confirm flag would not help, since the same model that calls the tool would set it. Deletion is also refused unlessB2_AUDIT_LOGis configured, and writes an INTENT record before acting and an OUTCOME record after -- on failure too, because a log that can miss events is not a log. WithB2_ARCHIVE_ROOTset, the bytes are copied locally first.The credentials boundary enumerates its fields.
b2_list_keysnames all nine fields it emits rather than spreading the SDK's key object, so a future SDK version that adds a secret-bearing field to a list response cannot leak it by accident. Key creation is deliberately not implemented for the same reason: B2 returns the live secret only fromcreateKey, and that value would land in a model's context window.Partial results announce themselves. Anything that can return less than the whole truth says so in the payload --
truncated/nextFileNameon file listings,truncated/anyTruncated/unfinishedLargeFileson usage,truncatedon key listings, andscopedToBucketIdwhen the application key's own restriction narrowed a whole-account listing to a single bucket. A partial answer presented as a complete one is worse than a refusal, because the caller cannot tell.Least-privilege keys are the tested path, not an afterthought. B2 rejects an unfiltered
b2_list_bucketsfrom a bucket-restricted key with a 401, and thelistAllBucketNamescapability does not exempt it -- so a server that only ever ran on a master key would ship broken for the credential its own docs mandate. That is exactly what happened here, and it was caught by rotating the key rather than by any test: a fakelistBuckets()agrees with whatever the caller does, so no fixture can catch an authorization rule.Downloads are written atomically. Bytes go to
<target>.<pid>.partial, are counted and length-checked, and are renamed onto the target only on a match. The SDK documents that a checksum failure errors the stream after bytes have flowed, so writing straight to the final path would leave a truncated file behind.Errors are returned, never thrown, across the MCP boundary. A throw tears down the stdio session; an error result lets the client read the reason and explain it.
On bucket usage
B2's API exposes no quota or usage endpoint -- caps and alerts live only in the
web console. b2_bucket_usage therefore sums file versions, including old
ones, because B2 bills for those too. Hide markers, folder markers, and start
records are excluded. Parts of unfinished large uploads are billed but not
summable, so they are reported separately as unfinishedLargeFiles and
bytesUsed is an honest floor rather than a total. The budget it is measured
against is project policy defined in code (10 GiB default, the B2 free tier),
not a B2 concept.
Related MCP server: rclone-mcp
Requirements
Node >= 22.3.0. This is a hard floor, not a preference -- the B2 SDK declares
it in engines. Pinned by .nvmrc, so run nvm use first if your shell
default is older; every command below fails on Node 20 and the failure does not
mention the version.
Setup
npm install
cp .env.example .env # then fill in .env; it is gitignored
npm test # 131 passing
npm run buildCreate an application key in the Backblaze console under Account > Application Keys. Use a regular scoped key, not the master key: the master key carries every capability, cannot be scoped, and cannot be deleted, only regenerated.
Environment
.env.example is committed documentation holding names only. Values go in
.env.
Variable | Required | Purpose |
| yes | Application key id. |
| yes | Application key secret. |
| for uploads | The only directory |
| for downloads | The only directory |
| for deletion | Append-only JSON Lines file, one object per mutation. Deletion is refused when unset. |
| optional | Where a copy of each deleted version is kept before it is destroyed. A manifest proves what existed; this keeps the bytes. |
Capabilities needed per tool: listBuckets/listFiles for the read tools,
writeFiles for upload, readFiles for download, deleteFiles for deletion,
listKeys for b2_list_keys. A Read Only key fails at the B2 API on any write,
by design.
Running
npm start # node dist/server.js (built)
npm run dev # tsx src/server.ts (from source)The server speaks MCP over stdio. Nothing is ever written to stdout except the protocol stream; diagnostics go to stderr.
Wiring it into a client
Add to your MCP client config (Claude Desktop, Claude Code, or any other MCP host):
{
"mcpServers": {
"b2": {
"command": "node",
"args": ["/absolute/path/to/b2-mcp-server/dist/server.js"]
}
}
}Credentials come from the .env file next to the package, so none appear in
client config.
Calling tools by hand
npx @modelcontextprotocol/inspector --cli npm run dev --method tools/list
npx @modelcontextprotocol/inspector --cli npm run dev \
--method tools/call --tool-name b2_bucket_usageEach argument needs its own --tool-arg, for example
--tool-arg bucketName=my-bucket.
Gotcha worth knowing: a relative localPath resolves against the configured
root, not your shell's working directory. With B2_UPLOAD_ROOT=".../uploads",
pass localPath=hello.txt, not localPath=uploads/hello.txt -- the latter
looks for uploads/uploads/hello.txt. The error message shows the candidate as
you gave it and deliberately not the resolved path, because that would print the
root.
Tools
Tool | Read/write | What it does |
| read | The buckets the key can see, with id, name, and type, plus |
| read | One page of current files in a bucket, optional |
| write | Uploads from |
| write (local) | Downloads to |
| write | Hides a file from listings. Reversible; the data stays in version history. |
| write | Removes the latest hide marker. Reports |
| destructive | Permanently destroys one version. Needs the exact |
| read | Bytes stored per bucket against a budget, flagging buckets over the threshold. Omit |
| read | Application keys with capabilities, bucket restrictions resolved to names, and derived expiry. No secrets. |
Every tool carries a zod input schema with per-field descriptions and MCP
annotations (readOnlyHint, destructiveHint, idempotentHint) set honestly,
so a client can decide what needs confirmation.
Testing
npm test131 tests across 12 files, no network and no credentials required -- modules
take the narrow structural type they actually use (BucketLister, not
B2Client), so a fake satisfies them while tsc still proves the real client
fits.
Several test files are regression coverage for bugs that a green suite would not otherwise catch, and their fixtures are shaped from observed dependency behavior rather than from what the API ought to do:
The B2 SDK throws errors with an empty
.message; the diagnosis lives onname/code/status. Reading.messagealone returned a blank string to the user for every B2-side failure.Node's
process.loadEnvFile()reports an unreadable file asENOENT, notEACCES, which downgrades "your .env has wrong permissions" to "you have no .env".
Where an invariant can be checked against real data instead of a fixture, it
was: usage was validated against a live account by the property that
b2_bucket_usage can never report fewer bytes than b2_list_files sums (it
exceeded it by exactly one 28-byte old version), and the delete path by a
four-way SHA-1 match across the original, the download, the archive copy, and
B2's own checksum. A fixture agrees with whatever the code does; a real corpus
does not.
Project layout
src/
server.ts MCP server, tool registration
config.ts credentials from the environment
env-file.ts .env loading (Node built-in, zero dependencies)
path-fence.ts read and write containment, both directions
atomic-write.ts temp file plus rename
audit-log.ts append-only JSON Lines mutation record
b2/ client, buckets, files, upload, download, delete, usage, keys
tests/ vitest, one file per module
claude-plans/ numbered design docs, written before the codeRoadmap
The full parked list lives in claude-plans/ROADMAP.md. The largest known gap:
b2_list_file_versions. Usage counts every version the account is billed for
while b2_list_files shows only current ones, so the server can report "you are
paying for 91 versions across 90 files" and offer no way to see the difference.
Deleting a current version promotes the next-oldest, which makes discovery
destructive-only today.
License
MIT.
Available Tools
9 toolsb2_bucket_usageReport bucket storage used against a budgetARead-only
Reports bytes stored per bucket and how that compares to a budget, flagging buckets over the threshold. B2 exposes no usage endpoint, so this is computed by summing every file version, INCLUDING old versions, which B2 also bills for. The figure EXCLUDES parts of unfinished large uploads, which B2 does bill for; those uploads are counted separately as unfinishedLargeFiles, so treat bytesUsed as a floor rather than a total. Omitting bucketName scans every bucket, which costs one transaction per 1000 versions per bucket and is the most expensive call this server makes. A scan is capped at 20 pages per bucket and sets truncated when the cap stops it.
Inputs: bucketName, budgetBytes, thresholdPercent.
b2_delete_file_versionPermanently delete one version of a B2 fileADestructiveIdempotent
PERMANENTLY destroys ONE version of a file. B2 cannot undo this, and older versions of the same name are left in place. Requires the exact fileId, which you must get from b2_list_files first: this tool will not look one up from a file name. Refused unless B2_AUDIT_LOG is configured, since every deletion is recorded. When B2_ARCHIVE_ROOT is set, a copy of the version is saved locally before it is destroyed. To remove a file from view reversibly, use b2_hide_file instead.
Inputs: fileId (required), fileName (required), bucketName (required).
b2_download_fileDownload a B2 file to local diskADestructiveIdempotent
Downloads a file from a bucket to the local filesystem and returns where it landed, its size, type, and SHA-1. The destination must sit inside the directory named by B2_DOWNLOAD_ROOT. An existing file is not replaced unless overwrite is true. File content is never returned, only the path it was written to.
Inputs: fileName (required), bucketName (required), localPath, overwrite.
b2_hide_fileHide a B2 fileAIdempotent
Hides a file so it stops appearing in b2_list_files. Reversible: the data stays in version history and b2_unhide_file restores it. Prefer this over deleting when the goal is to remove something from view.
Inputs: fileName (required), bucketName (required).
b2_list_bucketsList B2 bucketsARead-only
Lists every bucket in the configured Backblaze B2 account, as JSON objects with bucketId, bucketName, and bucketType.
Inputs: no named parameters.
b2_list_filesList files in a B2 bucketARead-only
Lists one page of current files in a bucket, as JSON objects with fileName, fileId, contentLength, contentType, and uploadedAt. Optionally filtered by name prefix. The result reports truncated and nextFileName when more files exist beyond the page.
Inputs: bucketName (required), limit, prefix.
b2_list_keysList B2 application keysARead-only
Lists the application keys on the account with their capabilities, bucket restrictions, name prefix, and expiry. Contains NO key secrets: B2 returns a secret only when a key is created, and this server never creates keys. It does reveal what each key is permitted to do. Requires a key carrying the listKeys capability; a key scoped only to file operations will be told so.
Inputs: no named parameters.
b2_unhide_fileUnhide a B2 fileAIdempotent
Removes the latest hide marker, making a hidden file visible again. If the file was not hidden, this reports restored false rather than failing.
Inputs: fileName (required), bucketName (required).
b2_upload_fileUpload a local file to a B2 bucketA
Uploads a file from the local filesystem into a bucket and returns the stored file id, name, size, and type. The local path must sit inside the directory named by B2_UPLOAD_ROOT; uploads are refused otherwise. Uploading an existing name adds a new version rather than replacing the old one.
Inputs: localPath (required), bucketName (required), fileName, contentType.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct resource and action: files (list/upload/download/hide/unhide/delete), buckets (list usage), and keys (list). The hide/delete pair is explicitly contrasted, preventing confusion. No two tools overlap in purpose.
Almost all tools follow a consistent b2_verb_noun pattern (e.g., b2_list_files, b2_upload_file, b2_hide_file). The sole exception is b2_bucket_usage, which uses a noun phrase rather than a verb, but it remains clear and does not disrupt overall readability.
Nine tools is well-scoped for a Backblaze B2 server. Each tool serves a distinct, necessary function, and there is no redundancy or bloat. The count feels appropriate for the domain.
The tool set covers file operations (list, upload, download, hide, delete) and includes bucket/key listing and usage, but misses bucket lifecycle (create/delete) and key management (create/delete). Hiding and unhiding work well, but no direct file metadata retrieval or bucket configuration exists. Core workflows are present, yet notable gaps remain.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server exposing the Backtest360 engine API as tools for AI agents.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables seamless integration with Backblaze B2 cloud storage for managing buckets, uploading/downloading files, handling large multipart uploads, and managing application keys through natural language interactions.3MIT
- AlicenseAqualityCmaintenanceMCP server for the Rclone RC API. Gives AI assistants the ability to manage cloud storage remotes, copy/sync files, list directories, and more — all through natural language.56393 npm14MIT
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that provides a bridge between MCP-compatible clients and MinIO object storage. It exposes MinIO operations as MCP tools for seamless bucket management and object operations.4-
- AlicenseNot gradedqualityDmaintenanceMCP server for AWS S3 and compatible object stores, enabling LLM clients to browse buckets and fetch objects.MIT No Attribution