Skip to main content
Glama
b2-mcp-server

b2-mcp-server

by ffumero2003

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 to B2_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 with realpath before the containment check, so a symlink inside the root cannot point outside it, and containment is target === root || target.startsWith(root + sep) -- a bare startsWith would admit the sibling directory /data/uploads-evil for 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_version takes an exact fileId and 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 unless B2_AUDIT_LOG is 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. With B2_ARCHIVE_ROOT set, the bytes are copied locally first.

  • The credentials boundary enumerates its fields. b2_list_keys names 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 from createKey, 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/nextFileName on file listings, truncated/anyTruncated/unfinishedLargeFiles on usage, truncated on key listings, and scopedToBucketId when 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_buckets from a bucket-restricted key with a 401, and the listAllBucketNames capability 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 fake listBuckets() 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 build

Create 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

B2_APPLICATION_KEY_ID

yes

Application key id.

B2_APPLICATION_KEY

yes

Application key secret.

B2_UPLOAD_ROOT

for uploads

The only directory b2_upload_file may read from. Unset means every upload is refused.

B2_DOWNLOAD_ROOT

for downloads

The only directory b2_download_file may write to. Unset means every download is refused.

B2_AUDIT_LOG

for deletion

Append-only JSON Lines file, one object per mutation. Deletion is refused when unset.

B2_ARCHIVE_ROOT

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_usage

Each 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

b2_list_buckets

read

The buckets the key can see, with id, name, and type, plus scopedToBucketId when the key is restricted to one.

b2_list_files

read

One page of current files in a bucket, optional prefix and limit, with truncated/nextFileName.

b2_upload_file

write

Uploads from B2_UPLOAD_ROOT into a bucket. Adds a version rather than replacing.

b2_download_file

write (local)

Downloads to B2_DOWNLOAD_ROOT, atomically. Returns the path and SHA-1, never the content. Will not replace an existing file unless overwrite is true.

b2_hide_file

write

Hides a file from listings. Reversible; the data stays in version history.

b2_unhide_file

write

Removes the latest hide marker. Reports restored: false rather than failing when nothing was hidden.

b2_delete_file_version

destructive

Permanently destroys one version. Needs the exact fileId, requires B2_AUDIT_LOG, honours B2_ARCHIVE_ROOT.

b2_bucket_usage

read

Bytes stored per bucket against a budget, flagging buckets over the threshold. Omit bucketName to scan every bucket.

b2_list_keys

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 test

131 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 on name/code/status. Reading .message alone returned a blank string to the user for every B2-side failure.

  • Node's process.loadEnvFile() reports an unreadable file as ENOENT, not EACCES, 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 code

Roadmap

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 tools
b2_bucket_usageReport bucket storage used against a budgetA
Read-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 fileA
DestructiveIdempotent

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 diskA
DestructiveIdempotent

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 fileA
Idempotent

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 bucketsA
Read-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 bucketA
Read-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 keysA
Read-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 fileA
Idempotent

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

    A4.3/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP 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.
      56
      393 npm
      14
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for AWS S3 and compatible object stores, enabling LLM clients to browse buckets and fetch objects.
      MIT No Attribution