Filecoin Onchain Cloud MCP

MCP server for decentralized file storage on Filecoin Onchain Cloud

@fil-b/foc-storage-mcp lets AI agents store and retrieve files on Filecoin's decentralized network through the Model Context Protocol (MCP), with automatic payment handling, CDN support, and dataset management.

Features

🛠️ 11 MCP Tools - Upload, manage, price, and pay for storage operations
📁 Dataset Organization - Group related files efficiently
💳 Automatic Payments - Built-in USDFC handling with gasless permits
⚡ CDN Support - Fast retrieval for frequently accessed files
💰 Cost Estimation - Calculate costs, explain pricing, convert units
🤖 AI-Ready - Designed for Claude, Cursor, and MCP clients

Configuration

Requirements:

Node.js >= 20.10.0 (Check version: node --version)
PRIVATE_KEY - Your Filecoin wallet private key (0x...)

Optional:

FILECOIN_NETWORK - mainnet (production) or calibration (testing, default)
TOTAL_STORAGE_NEEDED_GiB - Default storage capacity for calculations (default: 150 GiB)
PERSISTENCE_PERIOD_DAYS - Data retention duration (default: 365 days)
RUNOUT_NOTIFICATION_THRESHOLD_DAYS - Balance warning threshold (default: 45 days, recommended >30)
SYNAPSE_SOURCE - Source tag identifying this client to Synapse (default: foc-storage-mcp)

Note: Filecoin warm storage requires 30 days paid upfront. Keep balance above 30 days to maintain service.

Installation

Cursor

After installation, update PRIVATE_KEY in your config. Learn more

Claude Code

Add to .mcp.json:

{
  "mcpServers": {
    "foc-storage": {
      "command": "npx",
      "args": ["-y", "@fil-b/foc-storage-mcp"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here",
        "FILECOIN_NETWORK": "calibration"
      }
    }
  }
}

Learn more

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "foc-storage": {
      "command": "npx",
      "args": ["-y", "@fil-b/foc-storage-mcp"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here",
        "FILECOIN_NETWORK": "calibration"
      }
    }
  }
}

Learn more

VS Code

Create .vscode/mcp.json:

{
  "servers": {
    "foc-storage": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fil-b/foc-storage-mcp"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here",
        "FILECOIN_NETWORK": "calibration"
      }
    }
  }
}

Enable: Settings → Chat → MCP. Click "start" in mcp.json (Agent mode only). Learn more

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "foc-storage": {
      "command": "npx",
      "args": ["-y", "@fil-b/foc-storage-mcp"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here",
        "FILECOIN_NETWORK": "calibration"
      }
    }
  }
}

Restart Windsurf. Learn more

OpenAI Codex

codex mcp add foc-storage -- npx -y @fil-b/foc-storage-mcp

Edit config to add environment variables. Verify: codex mcp list. Learn more

Other Tools

Most MCP tools support this format:

{
  "mcpServers": {
    "foc-storage": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fil-b/foc-storage-mcp"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here",
        "FILECOIN_NETWORK": "calibration"
      }
    }
  }
}

Pricing

Pricing is read from the live Synapse v1 price list. Storage is billed per epoch (30 seconds) using the per-TiB monthly rate plus a recurring per-dataset service fee for non-empty datasets. Uploads can also include one-time create-dataset and add-pieces fees, and CDN egress is usage-based.

💡 Ask your agent: "How much to store 500 GiB for 6 months?"

Validation

npm test
npx tsc --noEmit
npm run build:mcp
npm run smoke:mcp:readonly
npm run build

smoke:mcp:readonly starts the built stdio server and exercises read-only MCP tools for pricing, providers, balances, and datasets. It deliberately skips upload, payment, withdrawal, and dataset-creation transactions; run those only with an intentionally funded Calibration wallet.

Tools

Ask naturally in Claude, Cursor, or any MCP client:

File Operations

uploadFile - Upload files with auto-payment
getDatasets - List all stored datasets
getDataset - Get dataset details
createDataset - Create new dataset container

Balance & Payments

getBalances - Check wallet and storage metrics
processPayment - Deposit USDFC tokens
processWithdrawal - Withdraw a specified USDFC amount to your wallet

Providers & Pricing

getProviders - List storage providers
estimateStoragePricing - Calculate costs
getStoragePricingInfo - Explain pricing models
convertStorageSize - Convert units

Usage Examples

"Check my storage balance"
"Upload presentation.pdf with CDN enabled"
"How much to store 2 TB for 1 year?"
"Create a dataset for Q4 reports"
"Show all my datasets"

Troubleshooting

Server not found: Verify npx --version, check JSON syntax, restart IDE

"PRIVATE_KEY is required": Add to env section, must start with 0x

Transaction fails: Check FIL for gas, verify network setting, confirm USDFC balance

"Invalid Version" or npm dependency errors:

Clear npm cache: npm cache clean --force
Clear npx cache: npx clear-npx-cache
Update npm: npm install -g npm@latest
As last resort, use older npm: npm install -g npm@10

Security

Never commit private keys or .env files
Test on Calibration network before mainnet
Keep balance >30 days (Filecoin warm storage requirement)
Monitor balance regularly with getBalances
Use hardware wallets for production

Contributing

Contributions welcome! Open an issue for major changes.

License

MIT © @nijoe1

Built with ❤️ by @FILBuilders for the Filecoin ecosystem

Foc Storage MCP

README