foc-storage-mcp by FIL-Builders - MCP Server

Filecoin Onchain Cloud MCP

MCP server for decentralized file storage on Filecoin Onchain Cloud

@fil-b/foc-storage-mcp provides AI agents with seamless access to Filecoin's decentralized storage network through the Model Context Protocol (MCP). Store files persistently with automatic payment handling, CDN support, and comprehensive dataset management.

Features

🛠️ 10 MCP Tools - Upload, manage, and price 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)

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

Storage: $2.50/TiB/month (pay-per-epoch: 30 seconds) • Min: $0.06/month

Example: 150 GiB for 1 year ≈ 0.44 USDFC ($0.44)

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

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

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

FIL-Builders/foc-storage-mcp