MCP Server Reference

Overview

The GolemDrive MCP server lets AI assistants (Claude Desktop, Cursor, Claude Code, or any MCP client) manage encrypted files through natural language. It exposes 104 tools, 8 resources, and 5 prompts over stdio transport (JSON-RPC over stdin/stdout).

Requirements: Node.js 18 or later.

Setup

Environment Variables

Variable	Required	Default	Description
GOLEMDRIVE_API_KEY	Yes	—	JWT token or API key. Whitespace-only values are rejected.
GOLEMDRIVE_API_URL	No	https://api.golemdrive.com	API base URL (trailing slashes stripped automatically).
GOLEMDRIVE_PASSPHRASE	No	—	User passphrase for E2EE file content operations (read, download, upload). If set, the keypair is loaded on startup.
GOLEMDRIVE_FILE_SERVER_URL	No	Same as GOLEMDRIVE_API_URL	File server URL for chunk upload/download.

Claude Desktop

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "golemdrive": {
      "command": "npx",
      "args": ["golemdrive-mcp"],
      "env": {
        "GOLEMDRIVE_API_KEY": "your-jwt-token",
        "GOLEMDRIVE_API_URL": "http://localhost:50080"
      }
    }
  }
}

Claude Code

Add to project .mcp.json:

{
  "mcpServers": {
    "golemdrive": {
      "command": "npx",
      "args": ["golemdrive-mcp"],
      "env": {
        "GOLEMDRIVE_API_KEY": "your-jwt-token"
      }
    }
  }
}

Cursor

Add to Cursor MCP settings with the same config format as Claude Desktop.

Local Development

cd mcp-server
npm install && npm run build
export GOLEMDRIVE_API_KEY="your-token"
node dist/index.js

---

Tools (104 total)

File Management (8 tools)

search_files

Search files and folders using full-text search. Supports quick, filtered, and content search modes.

Parameter	Type	Required	Description
query	string	Yes	Search query (min 2 characters)
mode	enum	No	quick (default), filtered, or content
category	string	No	Filter by file category (e.g. image, document, video)
ext	string	No	Filter by file extension (e.g. pdf, jpg)
date_from	string	No	Filter files created after this date (ISO 8601)
date_to	string	No	Filter files created before this date (ISO 8601)
page	number	No	Page number (default 1)
page_size	number	No	Results per page (1-100, default 20)
include_teams	boolean	No	Include team files in search results

Returns: Paginated search results with file/folder metadata.

list_files

List files and folders in a directory.

Parameter	Type	Required	Description
folder_uuid	UUID	No	Folder to list (root if omitted)
page	number	No	Page number (default 1)
page_size	number	No	Results per page (1-100, default 20)
sort_by	enum	No	name, size, or date

Returns: Paginated file/folder listing with metadata.

get_file_info

Get detailed metadata for a file or folder by UUID.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file or folder

Returns: Name, size, type, tags, labels, creation date, and more.

create_folder

Create a new folder.

Parameter	Type	Required	Description
name	string	Yes	Folder name
parent_uuid	UUID	No	Parent folder UUID (root if omitted)

Returns: Created folder metadata including UUID.

move_file

Move a file or folder to a different parent folder.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file or folder to move
target_folder_uuid	UUID	Yes	UUID of the destination folder

Returns: Updated file/folder metadata.

rename_file

Rename a file or folder.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file or folder to rename
new_name	string	Yes	New name

Returns: Updated file/folder metadata.

copy_file

Copy a file or folder to a target folder. Creates a duplicate.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file or folder to copy
target_folder_uuid	UUID	Yes	UUID of the destination folder

Returns: Copied file/folder metadata. Note: uses a two-step workflow (resolve target ID, then copy) with a known TOCTOU limitation.

delete_file

Delete a file or folder (moves to trash). Trashed items can be restored later or permanently deleted by emptying the trash.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file or folder to delete

Returns: Success confirmation.

---

Extended File Management (9 tools)

create_nested_folders

Create multiple nested folders in one call. Each folder level is created iteratively.

Parameter	Type	Required	Description
path	string	Yes	Slash-separated folder path (e.g. Work/Reports/2026). Max 20 levels.
parent_uuid	UUID	No	Parent folder UUID to start from (root if omitted)

Returns: Array of created folders with UUIDs, plus the leaf folder UUID.

restore_from_trash

Restore a previously deleted file or folder from the trash back to its original location.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the trashed file or folder to restore

Returns: Success confirmation.

empty_trash

Permanently delete all files and folders currently in the trash. This action is irreversible.

No parameters.

Returns: Success confirmation.

favorite_file

Add or remove a file/folder from favorites.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file or folder
action	enum	Yes	add or remove

Returns: Success confirmation.

set_file_description

Set or update the description text on a file or folder. Pass an empty string to clear.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file or folder
description	string	Yes	Description text (empty string to clear)

Returns: Updated file/folder metadata.

get_file_versions

List the version history of a file.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file

Returns: All stored versions with version IDs, timestamps, sizes, and uploaders.

restore_file_version

Restore a file to a previous version. The current version is preserved in history and the specified version becomes active.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file
version_id	string	Yes	ID of the version to restore

Returns: Restored file metadata.

classify_file

Set classification labels on a file for organization, filtering, and compliance.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file to classify
labels	object	Yes	Key-value pairs (e.g. {"category": "financial", "sensitivity": "internal"})

Returns: Updated file metadata with classification labels.

auto_classify_folder

Use AI to automatically categorize all files in a folder based on extensions and metadata. Token-gated: Standard = 100 files/month, Professional = 1000/month, Premium = unlimited.

Parameter	Type	Required	Description
folder_uuid	UUID	Yes	UUID of the folder to auto-classify
confirm_token_use	boolean	Yes	Must be true to confirm token usage

Returns: Classification results for each file in the folder.

---

File Content — E2EE Operations (5 tools)

All tools in this group require GOLEMDRIVE_PASSPHRASE to be set. Files are encrypted with AES-256-GCM client-side.

read_file_content

Read and decrypt a file, returning its content inline.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file to read
encoding	enum	No	text (default, max 10 MB) or base64 (max 50 MB)

Returns: File content as text or base64 string, plus file name and size. Returns an error if the file exceeds the size limit — use download_file instead.

download_file

Download and decrypt a file, saving it to the local filesystem. No size limit.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file to download
output_path	string	Yes	Local filesystem path to save the decrypted file. System directories (/etc, /usr, /bin, /sbin, /var, /proc, /sys, /dev) are rejected.

Returns: Success with saved path and file size.

download_folder

Download and decrypt an entire folder to a local directory. Recreates the folder structure locally.

Parameter	Type	Required	Description
folder_uuid	UUID	Yes	UUID of the folder to download
output_path	string	Yes	Local directory path. System directories rejected.

Returns: Count of files downloaded, skipped (already exist with matching size), and failed. Warns at 1 GB total, rejects at 5 GB. Downloads 5 files concurrently.

upload_file

Encrypt and upload a local file to GolemDrive.

Parameter	Type	Required	Description
local_path	string	Yes	Local filesystem path. System directories rejected. Max 500 MB.
folder_uuid	UUID	No	Target folder UUID (root if omitted)
file_name	string	No	Override file name (uses local filename if omitted)

Returns: Uploaded file UUID, name, and size.

upload_folder

Recursively encrypt and upload all files from a local directory. Creates matching folder structure on GolemDrive.

Parameter	Type	Required	Description
local_path	string	Yes	Local directory path
folder_uuid	UUID	No	Target folder UUID on GolemDrive (root if omitted)
recursive	boolean	No	Recurse into subdirectories (default true)

Returns: Count of files uploaded, folders created, total bytes, and any per-file errors. Individual files are capped at 500 MB.

---

Sharing (10 tools)

create_share_link

Create a new share link for a file or folder.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file or folder to share
storage_type	enum	No	VR_FILE (default) or VR_FOLDER
expiry_days	number	No	Days until the link expires. Omit for no expiry.
password	string	No	Plaintext password (hashed server-side with bcrypt)
download_limit	number	No	Max downloads before the link returns 410 Gone
allowed_emails	string[]	No	Up to 20 email addresses. Omit for public access.
access_mode	enum	No	download (default) or view_only
active_from	datetime	No	ISO 8601 datetime when the link becomes active
active_until	datetime	No	ISO 8601 datetime when the link deactivates

Returns: Share link details including short code, UUID, and all settings.

list_share_links

List all share links owned by the current user.

Parameter	Type	Required	Description
page	number	No	Page number, zero-based (default 0)
page_size	number	No	Items per page (1-100, default 20)

Returns: Array of share links with access counts, download counts, and status.

update_share_link

Update an existing share link’s settings.

Parameter	Type	Required	Description
short_code	string	Yes	Short code or UUID of the share link
expiry_days	number	No	New expiry in days from now
password	string	No	New password (bcrypt-hashed server-side)
is_active	boolean	No	false to deactivate, true to reactivate
access_mode	enum	No	download or view_only
allowed_emails	string[]	No	Replace allowed emails (empty array to clear, max 20)

Returns: Updated share link details.

delete_share_link

Delete a share link, permanently revoking access.

Parameter	Type	Required	Description
short_code	string	Yes	Short code or UUID of the share link

Returns: Success confirmation.

share_file_by_email

Create a share link and email it to a recipient. If email dispatch fails, the share link is still returned.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file to share
email	string	Yes	Recipient email address
expiry_days	number	No	Days until the link expires
view_only	boolean	No	If true, recipient can only view, not download

Returns: Share link details plus email_sent boolean.

bulk_create_share_links

Create share links for multiple files in a single request. Returns partial results on individual failures.

Parameter	Type	Required	Description
file_uuids	UUID[]	Yes	Array of file UUIDs (1-20)

Returns: Per-file results with short codes, plus total/succeeded/failed counts.

set_share_link_defaults

View or update the user’s default settings for new share links. Call with no parameters to view current defaults.

Parameter	Type	Required	Description
default_expiry_days	number	No	Default expiry in days (0 for no default). Omit to keep current.
default_access_mode	enum	No	download or view_only. Omit to keep current.
notify_on_download	boolean	No	Notify when a share link is downloaded. Omit to keep current.

Returns: Current or updated default settings.

toggle_share_link

Toggle a share link’s active state. If currently active, deactivates it; if inactive, activates it.

Parameter	Type	Required	Description
short_code	string	Yes	Short code or UUID of the share link

Returns: Previous and new active state.

set_share_page_theme

View or update the portal theme (share page branding). Call with no parameters to view current theme.

Parameter	Type	Required	Description
display_name	string	No	Display name on share pages (max 100 chars)
bio	string	No	Bio or tagline (max 500 chars)
logo_url	string	No	URL to logo image (must be HTTPS)
accent_color	string	No	Hex color #RRGGBB
background_color	string	No	Hex color #RRGGBB
css_class	enum	No	theme-dark, theme-light, theme-minimal, theme-bold, theme-elegant, or empty string to clear

Returns: Current or updated theme settings.

get_share_access_log

Get the access log for a share link showing who accessed it, when, and how much data was served. IP addresses are masked for privacy.

Parameter	Type	Required	Description
short_code	string	Yes	Short code of the share link

Returns: Array of access entries (email/anonymous, masked IP, bytes served, timestamp) with total count.

---

Teams (11 tools)

list_teams

Lists all teams the current user belongs to, including teams they own, administer, or are a member of.

No parameters.

Returns: Array of teams with names, roles, and member counts.

get_team_info

Retrieves detailed information about a specific team. Requires team membership.

Parameter	Type	Required	Description
team_uuid	UUID	Yes	UUID of the team

Returns: Team name, owner, member count, creation date.

list_team_members

Lists all members of a team with roles and join dates. Requires team membership.

Parameter	Type	Required	Description
team_uuid	UUID	Yes	UUID of the team

Returns: Array of members with roles (owner, admin, member), emails, and join dates.

create_team

Creates a new team. The current user becomes the owner.

Parameter	Type	Required	Description
name	string	Yes	Team name (1-255 characters)

Returns: Created team metadata including UUID.

invite_team_member

Send an invitation email to add a new member. Requires owner or admin role.

Parameter	Type	Required	Description
team_uuid	UUID	Yes	UUID of the team
email	string	Yes	Email address of the person to invite

Returns: Invitation details.

change_member_role

Change a team member’s role. Requires owner or admin role. The team owner’s role cannot be changed.

Parameter	Type	Required	Description
team_uuid	UUID	Yes	UUID of the team
user_id	UUID	Yes	UUID of the team member
role	enum	Yes	admin or member

Returns: Updated member details.

remove_team_member

Remove a member from a team. Requires owner or admin role. The team owner cannot be removed.

Parameter	Type	Required	Description
team_uuid	UUID	Yes	UUID of the team
user_id	UUID	Yes	UUID of the member to remove

Returns: Success confirmation.

get_team_quota

Retrieves storage, bandwidth, and member quota status for a team. Requires team membership.

Parameter	Type	Required	Description
team_uuid	UUID	Yes	UUID of the team

Returns: Current usage vs. limits for storage, bandwidth, and members.

get_team_permissions

Retrieves the RBAC permission matrix for the current user in a team.

Parameter	Type	Required	Description
team_uuid	UUID	Yes	UUID of the team

Returns: Allowed actions (invite, remove, edit, upload, etc.) based on the user’s role.

offboard_team_member

Offboard a member: removes them from the team and revokes all their shared file access. Requires owner or admin role.

Parameter	Type	Required	Description
team_uuid	UUID	Yes	UUID of the team
user_id	UUID	Yes	UUID of the member to offboard

Returns: Success confirmation.

get_team_storage_usage

Retrieves per-member storage usage breakdown for a team. Requires admin or owner role.

Parameter	Type	Required	Description
team_uuid	UUID	Yes	UUID of the team

Returns: Per-member storage consumption.

---

Social (18 tools)

get_profile

Retrieves a user’s public social profile.

Parameter	Type	Required	Description
user_id	UUID	Yes	UUID of the user

Returns: Display name, bio, avatar URL, follower/following counts, verification status.

update_profile

Updates the current user’s social profile. Only provided fields are updated.

Parameter	Type	Required	Description
display_name	string	No	New display name (max 100 characters)
bio	string	No	New bio (max 500 characters)
avatar_url	string	No	URL of the new avatar image

Returns: Updated profile data.

follow_user

Follow another user. Their public files and activity will appear in your feed. Mutual follows create a friends connection.

Parameter	Type	Required	Description
target_user_id	UUID	Yes	UUID of the person to follow

Returns: Follow confirmation.

unfollow_user

Unfollow a previously followed user.

Parameter	Type	Required	Description
user_id	UUID	Yes	UUID of the person to unfollow

Returns: Unfollow confirmation.

list_followers

Lists all users who follow the current user.

No parameters.

Returns: Array of followers with display names, usernames, and relationship status.

list_following

Lists all users the current user is following.

No parameters.

Returns: Array of followed users with display names, usernames, and relationship status.

get_feed

Retrieves the user’s social content feed showing recent activity from followed users.

Parameter	Type	Required	Description
page	number	No	Page number (default 1). Page size is controlled server-side.

Returns: Paginated feed entries.

send_tip

Send a monetary tip to a content creator’s tip jar. Supports fiat and token-based tips.

Parameter	Type	Required	Description
tip_jar_uuid	UUID	Yes	UUID of the recipient’s tip jar
amount	string	Yes	Tip amount as a decimal string (e.g. "5.00"). Range: 0.01-10000.00.
currency_type	enum	No	fiat (default) or tokens
token_amount	number	No	Token amount in cents (required when currency_type is tokens)
message	string	No	Optional message (max 1000 chars)
is_anonymous	boolean	No	Send tip anonymously

Returns: Tip confirmation and receipt.

follow_users_bulk

Follow multiple users in one operation.

Parameter	Type	Required	Description
user_ids	UUID[]	Yes	Array of user UUIDs (1-20)

Returns: Per-user results with success/failure, plus total counts.

get_follow_suggestions

Retrieves suggested users to follow based on mutual connections and activity.

No parameters.

Returns: Array of suggested users.

get_connection_status

Retrieves the connection status between the current user and a target user.

Parameter	Type	Required	Description
user_id	UUID	Yes	UUID of the user to check

Returns: Follow status, block status, and mute status.

block_user

Block a user. Blocked users cannot follow you, view your profile, or interact with your content. Automatically unfollows them.

Parameter	Type	Required	Description
user_id	UUID	Yes	UUID of the user to block

Returns: Block confirmation.

unblock_user

Unblock a previously blocked user.

Parameter	Type	Required	Description
user_id	UUID	Yes	UUID of the user to unblock

Returns: Unblock confirmation.

mute_user

Mute a user. Their activity is hidden from your feed without unfollowing. The muted user is not notified.

Parameter	Type	Required	Description
user_id	UUID	Yes	UUID of the user to mute

Returns: Mute confirmation.

set_username

Set or update the current user’s unique username.

Parameter	Type	Required	Description
username	string	Yes	1-30 characters, alphanumeric plus hyphens and underscores

Returns: Updated profile data.

set_vanity_url

Set or update the current user’s vanity URL slug (e.g. golemdrive.com/@slug).

Parameter	Type	Required	Description
vanity_url	string	Yes	3-30 characters, alphanumeric plus hyphens and underscores

Returns: Updated profile data.

set_profile_visibility

Set the visibility of the current user’s profile.

Parameter	Type	Required	Description
visibility	enum	Yes	public, private, or followers_only

Returns: Updated visibility setting.

report_user

Report a user for violating platform guidelines. Reports are reviewed by the moderation team.

Parameter	Type	Required	Description
user_id	UUID	Yes	UUID of the user to report
reason	enum	Yes	spam, harassment, impersonation, inappropriate_content, or other
details	string	No	Additional details (max 1000 chars)

Returns: Report confirmation.

---

Payments (15 tools)

get_subscription_info

Retrieves the current user’s subscription plan, status, renewal date, and tier details.

No parameters.

Returns: Subscription plan details.

get_token_balance

Returns the user’s remaining AI token balance.

No parameters.

Returns: Token balance.

get_ai_usage

Returns AI usage statistics for the current billing period, including token consumption and cost breakdown.

No parameters.

Returns: AI usage details.

get_billing_portal_url

Returns a URL to the Stripe billing portal for managing payment methods, invoices, and subscription details.

No parameters.

Returns: Stripe billing portal URL.

get_wallet_balance

Returns the user’s wallet balance including fiat balance, token holdings, and pending payouts.

No parameters.

Returns: Wallet balance details.

buy_ai_tokens

Returns available AI token packs with pricing. Since payment requires a browser checkout, this tool provides pack info and directs the user to complete the purchase in the dashboard.

No parameters.

Returns: Three packs — Starter (500 tokens, $4.99), Standard (2000 tokens, $14.99), Professional (10000 tokens, $49.99).

validate_coupon

Check whether a coupon or promo code is valid.

Parameter	Type	Required	Description
code	string	Yes	Coupon or promo code (1-50 characters)

Returns: Discount details, description, and expiration date.

get_spending_alerts

Retrieves the user’s spending alert preferences.

No parameters.

Returns: Monthly budget thresholds and notification settings.

set_spending_alerts

Update spending alert preferences.

Parameter	Type	Required	Description
monthly_budget	number	No	Monthly spending budget (positive number)
alert_threshold_percent	number	No	Percentage of budget at which to alert (1-100)
email_alerts_enabled	boolean	No	Enable/disable email alerts

Returns: Updated spending alert preferences.

create_creator_plan

Create a new subscription plan as a content creator.

Parameter	Type	Required	Description
name	string	Yes	Plan name (1-100 chars, e.g. “Supporter”)
price_monthly	string	Yes	Monthly price as decimal string (e.g. "4.99")
description	string	No	Description of benefits (max 500 chars)

Returns: Created plan metadata.

list_creator_plans

Lists all subscription plans the current user has created as a content creator.

No parameters.

Returns: Array of creator plans.

subscribe_to_creator

Subscribe to a creator’s plan. Starts a recurring payment.

Parameter	Type	Required	Description
plan_uuid	UUID	Yes	UUID of the creator plan

Returns: Subscription confirmation.

cancel_creator_subscription

Cancel a subscription to a specific creator. Access continues until the end of the current billing period.

Parameter	Type	Required	Description
creator_id	UUID	Yes	UUID of the creator

Returns: Cancellation confirmation.

get_creator_earnings

Returns the user’s creator earnings summary including total, pending, and paid out amounts, plus subscriber count.

No parameters.

Returns: Earnings breakdown.

request_token_withdrawal

Request a withdrawal of creator token earnings. Processed asynchronously.

Parameter	Type	Required	Description
amount	string	Yes	Withdrawal amount as decimal string (e.g. "50.00"). Range: 0.01-100000.00.

Returns: Withdrawal request confirmation.

---

Account (13 tools)

get_account_info

Returns the current user’s full account information including profile, subscription tier, storage quota, and settings.

No parameters.

Returns: Composite account data.

get_notifications

Retrieves the user’s most recent notifications.

Parameter	Type	Required	Description
limit	number	No	Max notifications to return (1-100, default 20)

Returns: Array of notifications (share invites, comments, follow events, system alerts).

mark_notification_read

Mark a single notification as read.

Parameter	Type	Required	Description
notification_id	string	Yes	ID of the notification

Returns: Confirmation.

check_recovery_key_status

Check whether the user has set up an encryption recovery key. Essential for regaining access to encrypted files if the passphrase is lost.

No parameters.

Returns: Recovery key setup status.

get_storage_usage

Returns a summary of storage usage: total quota, used space, file count, and bandwidth consumption. Extracts storage-relevant fields from the composite account endpoint.

No parameters.

Returns: Storage and bandwidth usage metrics.

setup_recovery_key

Initiate recovery key setup for the encrypted file vault. The server generates a recovery key that is shown only once.

Parameter	Type	Required	Description
passphrase_hash	string	Yes	Client-side PBKDF2-derived hash of the user’s passphrase (hex-encoded)

Returns: Recovery key (shown only once).

get_encryption_audit_log

Returns an audit trail of encryption-related events: key rotations, recovery key setup, and passphrase changes.

No parameters.

Returns: Array of encryption audit events.

request_account_deletion

Initiate a soft-deletion of the account. The account enters a 60-day grace period during which it can be restored. After 60 days, the account and all data are permanently deleted. Destructive operation.

No parameters.

Returns: Confirmation with grace period details.

restore_account

Cancel a pending account deletion and restore the account. Only works within the 60-day grace period.

No parameters.

Returns: Restoration confirmation.

get_email_preferences

Returns email notification preferences: share notifications, follow notifications, system announcements, and marketing emails.

No parameters.

Returns: Current email preference settings.

update_email_preferences

Update email notification preferences. Only provided fields are updated.

Parameter	Type	Required	Description
share_notifications	boolean	No	Enable/disable share notification emails
follow_notifications	boolean	No	Enable/disable follow notification emails
system_announcements	boolean	No	Enable/disable system announcement emails
marketing_emails	boolean	No	Enable/disable marketing emails
unsubscribe_all	boolean	No	Set to true to disable ALL email notifications at once

Returns: Updated preferences.

list_api_keys

Lists all API keys for the current user with names, prefixes, expiration dates, last-used timestamps, and active status.

No parameters.

Returns: Array of API key metadata.

create_api_key

Create a new API key for headless CLI or MCP access. The full key value is returned only once. Max 10 active keys per user.

Parameter	Type	Required	Description
name	string	Yes	Human-readable label (1-100 chars, e.g. “CI pipeline”)
expires_in	string	No	Expiration duration (e.g. 30d, 90d, 365d). Omit for never.

Returns: Full API key value (shown only once) plus metadata.

---

Comments (4 tools)

add_comment

Add a new top-level comment to a file.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file to comment on
text	string	Yes	Comment text (1-5000 characters)

Returns: Created comment with ID, body, author, and timestamp.

list_comments

List all comments on a file, including threaded replies, in chronological order.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file

Returns: Array of comments with nested replies and total count.

reply_to_comment

Reply to an existing comment, creating a threaded reply.

Parameter	Type	Required	Description
file_uuid	UUID	Yes	UUID of the file the comment belongs to
parent_id	string	Yes	ID of the parent comment
text	string	Yes	Reply text (1-5000 characters)

Returns: Created reply with ID, parent ID, body, author, and timestamp.

delete_comment

Delete a comment by ID. You can only delete your own comments.

Parameter	Type	Required	Description
comment_id	string	Yes	ID of the comment to delete

Returns: Success confirmation.

---

Webhooks & Retention (4 tools)

create_webhook

Register a new webhook endpoint that receives HTTP POST callbacks on specified events.

Parameter	Type	Required	Description
url	string	Yes	HTTPS callback URL. Private/internal IP ranges are blocked (localhost, 10.x, 172.16-31.x, 192.168.x, link-local, cloud metadata endpoints).
events	string[]	Yes	Event types to subscribe to (e.g. ["file.uploaded", "file.deleted"])

Returns: Created webhook details.

list_webhooks

Returns all webhook endpoints registered by the current user.

No parameters.

Returns: Array of webhooks with subscribed events and status.

delete_webhook

Remove a webhook. The endpoint stops receiving callbacks immediately.

Parameter	Type	Required	Description
webhook_id	string	Yes	ID of the webhook to delete

Returns: Success confirmation.

create_retention_rule

Create a data-retention policy for a folder. Files inside are automatically deleted after the specified number of days.

Parameter	Type	Required	Description
folder_uuid	UUID	Yes	UUID of the folder
delete_after_days	number	Yes	Days after which files are deleted (positive integer)
name	string	Yes	Human-readable name for the rule (1-255 chars)

Returns: Created retention rule details.

---

Diagnostics (4 tools)

diagnose_upload

Diagnose whether the user can upload a file of a given size. Checks storage quota, bandwidth limits, and file count.

Parameter	Type	Required	Description
file_size_bytes	number	No	Size of the file to upload in bytes. Omit for general quota status.

Returns: Diagnostic report with pass/fail/warn status for each check (storage_quota, bandwidth, file_count). Overall diagnosis: ready, warning, or upload_blocked.

check_share_link_health

Check the health of a share link. Verifies it exists, is active, has not expired, and has not exceeded download limits.

Parameter	Type	Required	Description
short_code	string	Yes	Short code of the share link

Returns: Health status (healthy or issues_found) with a list of issues (deactivated, expired, at download limit, not yet active, active window ended) and link info.

verify_encryption_status

Verify the user’s E2EE setup status. Checks keypair existence and recovery key configuration.

No parameters.

Returns: encryption_ready boolean, recovery_key_configured boolean, per-check details, and recommendations.

check_service_health

Check GolemDrive API server health and response time.

No parameters.

Returns: Reachability status, response time in milliseconds, and server health payload.

---

Compute (1 tool)

Runs entirely in the MCP server. No API call is made.

compute

Perform local data aggregation and formatting operations on provided values.

Parameter	Type	Required	Description
operation	enum	Yes	sum, count, average, min, max, filter, sort, format_bytes, format_table
values	array	No	Array of values to operate on. Numbers for numeric ops; objects for filter/sort/format_table; numbers for format_bytes.
field	string	No	Field name when values are objects. Used with sum, average, min, max, sort, filter.
filter_op	enum	No	eq, neq, gt, gte, lt, lte, contains, startsWith, endsWith. Required for filter.
filter_value	any	No	Value to compare against. Required for filter.
sort_order	enum	No	asc (default) or desc
columns	string[]	No	Column names for format_table. Defaults to object keys from the first row.

Returns: Computed result. format_table returns a plain-text ASCII table; format_bytes returns human-readable sizes; others return numeric results with counts.

---

CLI Generator (1 tool)

Runs entirely in the MCP server. No API call is made.

generate_cli_command

Generate GolemDrive CLI commands for common operations.

Parameter	Type	Required	Description
operation	string	Yes	One of: upload, download, download_folder, list, tree, search, share, mkdir, move, delete, verify, info, versions, recovery_key, tokens, teams, config
file_path	string	No	Local file path for upload operations
file_uuid	string	No	File or folder UUID for targeted operations
target_folder_uuid	string	No	Target folder UUID for move/upload
query	string	No	Search query or folder name for mkdir
options	object	No	Additional CLI flags as key-value pairs (e.g. {"expiry": "7d", "password": "secret"})

Returns: Complete CLI command string, description, examples, and available flags for the operation.

---

Audit (1 tool)

get_share_audit_log

Enhanced share access audit with date-range filtering, summary statistics, and aggregated access patterns. IP addresses are masked for privacy.

Parameter	Type	Required	Description
short_code	string	Yes	Short code of the share link to audit
date_from	datetime	No	Only include accesses after this ISO 8601 datetime
date_to	datetime	No	Only include accesses before this ISO 8601 datetime
include_summary	boolean	No	Include summary statistics (default true)

Returns: Filtered access entries (masked IPs, formatted bytes), optional summary (total accesses, unique visitors by email and IP, total bytes served, accesses-by-day breakdown).

---

Resources (8)

Resources are read-only data endpoints that AI assistants can browse.

URI	Description	Backend Endpoint
golemdrive://files	Root-level file and folder listing (page 1, 50 items)	GET /v2/nodes?page=1&page_size=50&state=active
golemdrive://files/{uuid}	Metadata for a specific file or folder by UUID	GET /v2/nodes/{uuid}
golemdrive://shares	All active share links (page 0, 50 items)	GET /api/v1/webshare/url?page=0&size=50
golemdrive://teams	Teams the user belongs to (page 1, 50 items)	GET /api/v1/team?page=1&page_size=50
golemdrive://teams/{uuid}	Team details including members and roles	GET /api/v1/team/{uuid}
golemdrive://profile	Current user’s social profile (display name, avatar, visibility)	GET /api/v1/social/profile
golemdrive://usage	Storage quota + AI usage composite (two API calls merged)	GET /api/v1/useraccount/composite + GET /api/v1/ai/usage
golemdrive://notifications	Unread in-app notifications (limit 50)	GET /api/v1/social/notifications?unread_only=true&limit=50

UUID parameters are validated (v4 format). Invalid UUIDs return an error resource. All resources return application/json.

---

Prompts (5)

Pre-built prompt templates that AI agents can invoke for common GolemDrive workflows.

organize_files

Analyze the user’s files and suggest how to organize them by type, date, or project. The prompt instructs the agent to read golemdrive://files, build a full folder tree, identify patterns (file types, naming conventions, date clusters), suggest a reorganized structure with specific move actions, and highlight duplicates or misplaced files.

share_summary

Summarize all active share links with access counts, expiry dates, download limits, and security status. Groups links by status (active, expiring soon, expired, at download limit). Highlights security concerns such as links with no expiry and no password.

storage_audit

Audit storage: check usage vs. quota, find the 10 largest files, identify files not modified in 90+ days, calculate potential space savings, and check bandwidth usage trends. Presents findings in sections (Usage Overview, Top 10 Largest Files, Stale Files, Recommended Actions).

team_overview

Show all teams with member lists, roles, and shared folder counts. Flags any team where the user is the sole admin or owner (single point of failure). Recommends additional admins where needed.

security_check

Verify security posture: recovery key status, recent security notifications, share link hygiene (links without expiry or password), and overall security scorecard with prioritized recommendations.

---

Security

The MCP server implements multiple security layers:

• Authentication — All API requests include the GOLEMDRIVE_API_KEY as a Bearer token in the Authorization header.
• HTTPS enforcement — Webhook URLs must use HTTPS. HTTP URLs are rejected at registration time.
• Private IP blocking — Webhook URLs targeting private/reserved IP ranges are rejected to prevent SSRF. Blocked ranges: 127.x, 10.x, 172.16-31.x, 192.168.x, 169.254.x (link-local), fc00:/fd (IPv6 ULA), fe80: (IPv6 link-local), ::1, 0.0.0.0, metadata.*, internal.*.
• UUID validation — All UUID parameters are validated with Zod’s .uuid() validator. Path parameters are encoded with encodeURIComponent() to prevent path traversal.
• Path traversal prevention — File content tools validate output paths and reject system directories (/etc, /usr, /bin, /sbin, /var, /proc, /sys, /dev). Server-provided filenames are sanitized with path.basename().
• Crypto error sanitization — Error messages containing crypto terms (decrypt, encrypt, AES, RSA, PBKDF, etc.) are replaced with a generic “Encryption operation failed” message to avoid leaking key lengths, algorithm details, or buffer contents.
• IP address masking — Share access logs mask the last octet of IPv4 addresses and the last 4 groups of IPv6 addresses.
• Size limits — read_file_content: 10 MB text, 50 MB base64. download_folder: 5 GB max (warns at 1 GB). upload_folder: 500 MB per file. Pagination capped at 100 items for tools, 50 items for resources.
• Nesting limits — create_nested_folders caps at 20 levels deep.
• Tip amount bounds — send_tip validates 0.01-10000.00 range. request_token_withdrawal validates 0.01-100000.00 range.

---

Error Format

All tool errors follow a consistent format:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"error\": \"Human-readable error message\"}"
    }
  ]
}

Errors are caught by the safeHandler wrapper. Crypto-related error messages are sanitized before being returned.