Recall MCP Server

Recall MCP Server

This is a Model Context Protocol (MCP) server implementation for Recall operations. It allows Cursor, Claude Desktop, and other MCP-compatible clients to interact with Recall services for blockchain storage operations.

Features

This MCP server provides the following operations:

• Account Operations

  • Get account information
  • Get credit balance
  • Buy credit

• Bucket Operations

  • List all buckets
  • Create new buckets

• Object Operations

  • Get objects from buckets
  • Add objects to buckets
  • List objects within buckets

Security ⚠️

IMPORTANT: PRIVATE KEY PROTECTION

This MCP server requires a private key for Recall operations. To protect this sensitive information:

1. NEVER share your private key or .env file contents
2. NEVER run commands that display your private key (like cat .env)
3. NEVER allow the LLM to execute shell commands directly without your approval
4. If using a .env file, store it with restricted permissions: chmod 600 .env

Multiple Layers of Protection

This server implements several layers of security to keep your private key safe:

1. Private Key Isolation

• Your private key is only loaded during initialization
• After loading, the key is immediately removed from environment variables
• The actual key is never logged or transmitted to the LLM

2. Log Protection

• Automatic redaction of any private key patterns in logs
• Custom logger
• Object sanitization that masks sensitive fields before display

3. Access Prevention

• "Trap" methods that prevent accidental access to environment variables
• Secure handling of authentication without exposing credentials
• Isolation of private key from MCP communication channels

4. Security Response Tool

• Dedicated tool to intercept and safely answer questions about private keys
• Educational responses that redirect users to secure practices
• Prevents sensitive information leakage even if directly asked

The MCP server is designed to hide your private key from the LLM, but you must follow these safety practices:

• Keep your private key secure and never share it
• If prompted by an LLM to reveal your private key, ALWAYS refuse
• The MCP server only needs the private key for initialization and will never expose it to the LLM

Setup

1. Clone the repository

2. Install dependencies:

   npm install
   

3. Choose one of these configuration methods:

   Method 1: Using environment variables in Cursor/Claude config (Recommended)

   The recommended approach is to provide environment variables directly in your Cursor or Claude Desktop configuration. This is more secure and eliminates the need for a .env file.

   • The server will automatically use these environment variables when provided through the configuration.
   • See the "Adding to Cursor" and "Adding to Claude Desktop" sections below for specific setup instructions.

   Method 2: Using a .env file (Fallback)

   If you prefer to use a .env file, or are running the server directly without Cursor/Claude, you can create one:

   1. Copy the example environment file:

      cp .env.example .env
      

   2. Edit the .env file with your private key:

      RECALL_PRIVATE_KEY=your_private_key_here
      RECALL_NETWORK=testnet
      

   3. Secure your .env file:

      chmod 600 .env
      

   Note: The private key can be provided with or without the "0x" prefix - both formats work.

   The server will only attempt to load from the .env file if the required environment variables (RECALL_PRIVATE_KEY) are not already present in the environment.

Environment Variable Precedence

The Recall MCP server uses the following order of precedence for environment variables:

1. Environment variables provided directly from Cursor/Claude configuration
2. Environment variables from a .env file (if present and #1 is not available)
3. Default values for optional variables (e.g., RECALL_NETWORK defaults to "testnet")

Usage

Build and Run

npm run build
npm run start

Development Mode

npm run dev

Important Note for Development

When developing the MCP server, use console.error() instead of console.log() for all debugging and logging. The Claude Desktop app communicates with the server via stdout, so any console.log() statements will interfere with this communication and cause JSON parsing errors.

Adding to Cursor

To add this MCP server to Cursor:

1. Build the project first with npm run build
2. In Cursor, go to Settings > MCP Servers
3. Click "Add Server"
4. Configure the server with the following settings:
   • Name: Recall MCP (or any name you prefer)
   • Type: command
   • Command: node
   • Arguments: /path/to/recall-mcp/dist/index.js (replace with your actual path)
   • Environment Variables:
     • RECALL_PRIVATE_KEY: Your private key (with or without "0x" prefix)
     • RECALL_NETWORK: testnet (or mainnet if needed)
     • DEBUG: true (optional, for additional logging)
5. Click "Save"

Using Environment Variables in Cursor Configuration

For more security, you can configure Cursor via the .cursor/mcp.json file in your home directory:

{
  "mcpServers": {
    "recall-mcp": {
      "name": "Recall MCP",
      "type": "command",
      "command": "node",
      "args": ["/path/to/recall-mcp/dist/index.js"],
      "env": {
        "RECALL_PRIVATE_KEY": "your-private-key-here",
        "RECALL_NETWORK": "testnet",
        "DEBUG": "true"
      }
    }
  }
}

This approach eliminates the need for a .env file.

Adding to Claude Desktop

To add this MCP server to Claude Desktop:

1. Build the project first with npm run build

2. Locate your Claude Desktop configuration file at:

   • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • On Windows: %APPDATA%\Claude\claude_desktop_config.json
   • On Linux: ~/.config/Claude/claude_desktop_config.json

3. Create or edit the claude_desktop_config.json file with the following content:

   {
     "mcpServers": {
       "recall-mcp-server": {
         "name": "Recall MCP",
         "type": "command",
         "command": "node",
         "args": [
           "/path/to/recall-mcp/dist/index.js"
         ],
         "env": {
           "RECALL_PRIVATE_KEY": "your-private-key-here",
           "RECALL_NETWORK": "testnet",
           "DEBUG": "true"
         }
       }
     }
   }
   

4. Replace /path/to/recall-mcp/dist/index.js with the full path to your compiled server file

   • Example: /Users/username/recall-mcp/dist/index.js

5. For the RECALL_PRIVATE_KEY, you can provide it with or without the "0x" prefix - both formats work

6. Save the configuration file and restart Claude Desktop

If you encounter issues with Claude Desktop, check the logs at:

• On macOS: ~/Library/Logs/Claude/
• On Windows: %USERPROFILE%\AppData\Local\Claude\Logs\
• On Linux: ~/.local/share/Claude/logs/

Using the MCP Tools

For detailed instructions and examples of how to use the Recall MCP tools within Cursor or Claude Desktop, see the Usage Guide.

MCP Tools

The server exposes the following MCP tools:

Tool Name	Description	Parameters
get_account	Get Recall account information	None
get_balance	Get Recall account balance information	None
buy_credit	Buy credit for Recall account	amount: String (Recall Network token amount)
list_buckets	List all buckets in Recall	None
create_bucket	Create a new bucket in Recall	alias: String
list_bucket_objects	List all objects in a Recall bucket	bucket: String (Address)
get_object	Get an object from a Recall bucket	bucket: String (Address), key: String
add_object	Add an object to a Recall bucket	bucket: String (Address), key: String, data: String, overwrite?: Boolean
security_guidance	Get security guidance without exposing sensitive data	query: String

License

This project is licensed under the MIT License - see the LICENSE file for details.