foc-storage

foc-storage is an MCP server that exposes Filecoin Onchain Cloud storage capabilities to AI agents via the Model Context Protocol. It provides a suite of 10 MCP tools for uploading files, managing datasets, handling automatic payments, and estimating pricing with CDN support for fast retrieval. You can interact with these tools through any MCP client (Claude, Cursor, or your own integration) by invoking commands like uploadFile, getDatasets, getDataset, createDataset, getBalances, estimateStoragePricing, and convertStorageSize. The server is designed to work with a Filecoin wallet (PRIVATE_KEY) and can target either the calibration or mainnet network via the FILECOIN_NETWORK setting. When used in an MCP context, you can describe tasks to your agent (e.g., “Upload presentation.pdf with CDN enabled” or “How much to store 2 TB for 1 year?”) and the agent will translate them into MCP tool calls that the foc-storage server executes and responds to.

Setup typically involves configuring your environment with your wallet key and network preference, then running the MCP server through npx with the appropriate package name. Tools like getBalances, processPayment, and getProviders help you manage payments and storage options, while the dataset-related tools organize and query stored data. The CDN-enabled upload and pricing helpers streamline persistent storage decisions within your AI workflows.

Prerequisites:

• Node.js >= 20.10.0
• Access to a Filecoin wallet private key (starts with 0x)
• Optional: FILECOIN_NETWORK (mainnet or calibration)

Installation steps:

1. Ensure Node.js is installed and accessible:
   • Check: node --version
   • If needed, install from https://nodejs.org/
2. Install or run the MCP server via npm/npx using the package name from the README:
   • npm install -g @fil-b/foc-storage-mcp (optional, for global use)
   • Or run directly with npx as part of the MCP config: npx -y @fil-b/foc-storage-mcp
3. Prepare environment variables in your MCP integration configuration:
   • PRIVATE_KEY: your_filecoin_private_key_here
   • FILECOIN_NETWORK: calibration or mainnet (default calibration)
4. Add the server to your MCP client configuration (example provided in Claude Code, Claude Desktop, VS Code, Windsurf, OpenAI Codex, or Other Tools sections of the README).
5. Start using the Tools: uploadFile, getDatasets, createDataset, getBalances, estimateStoragePricing, etc.

Note: For production, ensure you keep PRIVATE_KEY secure and monitor balance to satisfy the 30-day upfront cost for Filecoin warm storage as documented in the project notes.

Tips and notes:

• Ensure PRIVATE_KEY starts with 0x and is kept secure; never commit keys to source control.
• If you encounter “Invalid Version” or npm dependency errors, try clearing caches: npm cache clean --force and npx clear-npx-cache, then update npm.
• The FILECOIN_NETWORK can be set to calibration for testing; switch to mainnet when ready for production.
• The storage pricing is calculated per epoch with a suggested default storage capacity (e.g., 150 GiB) and retention periods; use estimateStoragePricing and convertStorageSize to plan costs.
• If you see balance warnings, adjust RUNOUT_NOTIFICATION_THRESHOLD_DAYS or top up funds to avoid service interruption.
• Many MCP clients (Claude, Cursor, Windsurf, VS Code, etc.) provide UI flows to add the foc-storage MCP server; follow the integration guides in the README for each tool.