Connect AI Clients with the MCP Server

The Walrus Console MCP server gives an AI client the same file and folder operations you get in the web app. Your agent creates folders, uploads and downloads files, and checks storage usage, while encryption and signing stay on your machine.

The package is @mysten-incubation/walrus-console-mcp, licensed MIT.

Prerequisites

• Node.js 24 or later. The package sets "node": ">=24" in its engines field.
• A Walrus Console account with an API key. Open console.walrus.xyz, sign in, then click Integrations and Create API Key in the top-right corner. Name the key and give it the read_write role.
• The values Console reveals. It shows them once: the hbr_ API key, the suiprivkey1 service private key, and a CONSOLE_CREDENTIAL_BUNDLE value that carries both keys plus two Sui addresses. Copy the bundle if you can. It is the installer's first prompt.

The API key authorizes calls to Console. The service private key signs onchain access grants and unwraps Seal keys locally, which is why the server needs both. The two addresses in the bundle are your Console account address and the address of the space's Management API key signer, if any. create_bucket checks the transaction it signs against them and refuses to run without the account address.

Install

Run the interactive installer from a fresh directory:

$ npx -y @mysten-incubation/walrus-console-mcp@beta install

The installer:

1. Asks for the credential bundle, or for the API key and service private key one at a time followed by the two addresses.
2. Validates the API key against the Console API, shows the addresses it is about to pin, and saves nothing until you confirm.
3. Asks which folders upload_file and download_file can use when your client does not share workspace folders.
4. Installs the server into its own directory and registers it with the agents you tick: Claude Desktop, Claude Code, Cursor, Codex, and Gemini CLI.

It writes the credentials to ~/.config/walrus-console-mcp/config.json, or %APPDATA%\walrus-console-mcp\config.json on Windows, with user-only permissions. Your MCP client configuration never holds the keys. It only launches the server.

Environment variables override the saved file, so CONSOLE_API_KEY and CONSOLE_SERVICE_PRIVATE_KEY still work for CI. The server also reads CONSOLE_WEB_ACCOUNT_ADDRESS and CONSOLE_KEY_ADMIN_ADDRESS for the two address pins, CONSOLE_ADMIN_KEY and CONSOLE_ADMIN_SERVICE_PRIVATE_KEY for the Key-Admin credential, CONSOLE_MCP_ALLOWED_DIRS for file access, and CONSOLE_API_BASE_URL to point at a different Console deployment.

Register the server with your client

Client	Command
Claude Code	claude mcp add --scope user walrus-console-mcp -- npx -y @mysten-incubation/walrus-console-mcp@beta
Codex	codex mcp add walrus-console-mcp -- npx -y @mysten-incubation/walrus-console-mcp@beta
Claude Desktop	The installer configures it for you

--scope user makes the server available in every project. Use --scope local to limit it to the current one.

For Cursor, Gemini CLI, or any hand-written configuration, add a stdio server that runs the package through npx:

{
  "mcpServers": {
    "walrus-console-mcp": {
      "command": "npx",
      "args": ["-y", "@mysten-incubation/walrus-console-mcp@beta"]
    }
  }
}

The server name is a local label. The launcher it runs is what matters.

Restart the client, run /mcp, and approve walrus-console-mcp when prompted.

Verify

Ask the agent to call ping_console. It confirms which credentials the server loaded and reports has_api_key, has_service_key, has_admin_key, and has_admin_signer as booleans, plus the network the server resolved. It never echoes the values themselves.

Available tools

Tool	What it does	Access
ping_console	Confirm the configured keys	Read
list_spaces	List your Personal and Team spaces	Read
get_storage_usage	Aggregate storage usage for a space	Read
list_buckets	List the folders in a space	Read
get_bucket	Fetch one folder's metadata	Read
get_bucket_metadata	Fetch a folder's custom metadata	Read
create_bucket	Create a private encrypted folder. Needs the pinned account address	Write
rename_bucket	Rename a folder	Write
update_bucket_metadata	Set a folder's custom metadata	Write
delete_bucket	Delete a folder and its files permanently	Write
upload_file	Encrypt and upload a local file	Write
download_file	Download and decrypt a file to disk	Read
list_files	List the files in a folder, with search	Read
get_file_status	Check upload progress	Read
update_file	Update a file's name, description, or tags	Write
delete_file	Delete one file permanently	Write
generate_api_key	Mint a scoped child key	Write

A read_only API key can call the read tools. The write tools need a read_write key.

Where the server can read and write files

upload_file and download_file resolve relative paths, and a leading ~, against your workspace rather than the server's install directory. Path access fails closed: the server confines both tools to the roots your MCP client advertises, or to the folders you saved at install time, and rejects a path when it has neither.

Clients that advertise your open workspace folders need no extra configuration. Claude Desktop does not advertise roots, so name the folders during install, or set CONSOLE_MCP_ALLOWED_DIRS to the directories the server might touch, separated by :, or by ; on Windows:

$ export CONSOLE_MCP_ALLOWED_DIRS="$HOME/Documents:$HOME/Downloads"

The server resolves symlinks before it checks containment, so a link inside an allowed root that points outside it gets rejected rather than followed. A path the model invents, including one arriving through prompt injection, cannot reach a file outside those roots.

Mint keys for other agents

generate_api_key lets an orchestrator mint scoped working keys for worker agents or CI, without a person opening Console and copying values out of the shown-once dialog. Two credential types keep the roles apart:

Credential	Prefix	What it can do
Working key	hbr_	List and create folders, upload and download files. Cannot mint.
Key-Admin	hbradm_	Mint child keys and sign their access grants. No data-plane access.

Keep the working key on every host, and the Key-Admin credential on the provisioning host only. Configure it with the installed launcher, either interactively with config and the Management key choice, or scripted:

$ "${XDG_DATA_HOME:-$HOME/.local/share}/walrus-console-mcp/node_modules/.bin/walrus-console-mcp" config --admin-key hbradm_… --admin-signer suiprivkey1…

Given a permission and an optional label, the tool generates a child keypair locally, mints a child hbr_ key, runs one sponsored grant_bucket_access transaction signed with the admin seed, and polls until the key becomes active. It then writes the child's hbr_ key and suiprivkey1 private key to a user-only file under ~/.config/walrus-console-mcp/minted-keys/ and returns the path as credential.credentialFile. The secrets appear nowhere else, including the tool's own output.

The Key-Admin credential determines the space. You pass spaceId so the tool can check, after the mint, that the key landed where you expected. When a step after the mint fails, the result is ok: false with a stage of space-check, grant, activation, or persist, and it usually still carries the credential file. The key already exists at that point, so do not call the tool again to retry. A second call mints a second key and orphans the first, and only the Console web app can revoke it.

The mint-time grant covers the private folders that already exist in the space. A folder the server creates later includes a child key only when that key is still active and is already a member of one of the access groups the server recorded. Keys the server had to leave off appear in roster.droppedCandidates of the create_bucket result. Repair them with a Key-Admin grant, not a new mint.

Calling generate_api_key with only a working key configured returns an error and makes no network call.

What stays on your machine

Console never receives your plaintext files or your decryption keys. The service private key never leaves your machine, and encryption, decryption, and signing all happen locally. The server talks to Console with your API key alone.

A leaked working key cannot mint or escalate. A leaked Key-Admin credential can, and it also implies read access onchain, so keep it off worker hosts and revoke it separately if it escapes.