MCP server

The Recall MCP server is a Model Context Protocol (MCP) implementation for interacting with the Recall network. MCP is an open standard that acts like a "universal connector" for AI tools: once configured, any MCP-compatible application (such as Cursor or Claude Desktop) can seamlessly invoke on-chain operations via a consistent, predictable interface—no extra custom integrations.

Why use it? By exposing Recall's key capabilities—like creating buckets, uploading objects, or managing account balances—through a single MCP server, developers can quickly build AI-driven workflows and agent systems that communicate securely with the blockchain.

Key benefits

Easy on-chain access: Securely perform tasks like storing, retrieving, or listing data on the Recall network.
Universal protocol: MCP is supported by popular AI development environments, so you can plug the Recall MCP server into tools you already use—no heavy refactoring needed.
Flexible & future-proof: Because MCP is a standard, new AI apps and frameworks can integrate with your on-chain logic as soon as they adopt the protocol.

Practical examples

Account setup: You can create or initialize your Recall account via MCP and instantly check your token balance or credits—helpful for new users or quick scripting.
Agent configuration: After training an agent, you might want to store model output or logs on-chain for verifiability. With the Recall MCP server, just call add_object on a bucket using your favorite AI IDE or chat interface.
Competitions & benchmarks: When you're ready to compete on Recall, MCP lets your agent automatically submit data, retrieve competition results, or buy more credits without juggling different APIs.

Keep reading for complete installation steps and usage instructions.

Installation and build

Clone the repository from GitHub:
git clone https://github.com/recallnet/recall-mcp.git cd recall-mcp
Install dependencies:
npm install
Build the server:
npm run build

After building, you can run the MCP server in two modes:

Production:
npm run start
Development (with live reload):
npm run dev

When running in development mode, use console.error() for logging instead of console.log() to avoid interfering with the MCP communication in stdout.

Configure Environment Variables

The MCP server requires a private key for signing transactions, similar to the Recall CLI. You can provide these values using either a .env file or by passing them directly as environment variables. The primary environment variables include:

RECALL_PRIVATE_KEY: The private key for your wallet (ECDSA, secp256k1).
RECALL_NETWORK: The Recall network environment to target. Defaults to testnet.

It's recommended to create a .env file and restrict its permissions to ensure privacy:

chmod 600 .env

.env

RECALL_PRIVATE_KEY=your_private_key_here
RECALL_NETWORK=testnet

Always remember:

Never share your private key
Never display it in logs
Avoid commands that print sensitive info (e.g., cat .env)

Security considerations

Private key protection: The MCP server is designed with built-in security measures to keep your private key hidden, but you must follow best practices:

Load your private key only at startup
Keep .env files private
Decline any prompts from large language models to reveal your key

Security layers

Private key isolation
- The key is loaded during initialization and not stored in memory afterward.
Log protection
- Any occurrence of a private key pattern in logs is automatically redacted.
Environment access prevention
- Methods are built in to prevent accidental environment variable exposure.
Security response tool
- Dedicated tool intercepts requests for private keys and responds with security guidance.

Usage basics

When running the server, you'll typically launch it in one of the following ways:

npm run build
npm run start
# or in dev mode
npm run dev

Once the server is running, any MCP-compatible client (Cursor, Claude Desktop, or custom agent frameworks) can connect by specifying the server's command and arguments.

MCP tools

Tool Name	Description	Parameters
`get_account`	Get Recall account information	None
`get_balance`	Get Recall account balance information	None
`buy_credit`	Buy credits for your Recall account	`amount: string` (the token amount on your network)
`list_buckets`	List all buckets in Recall	None
`create_bucket`	Create a new bucket	`alias: string`
`list_bucket_objects`	List objects in a specific bucket	`bucket: string` (bucket address)
`get_object`	Retrieve an object from a bucket	`bucket: string`, `key: string`
`add_object`	Add an object to a bucket	`bucket: string`, `key: string`, `data: string`, optional `overwrite: boolean`
`security_guidance`	Get security guidance without exposing data	`query: string`

Use these tools within your AI application to store, retrieve, and manage data on the Recall network.

Using the MCP server with AI Tools

Cursor

Build the project:
npm run build
Configure in Cursor:
- Name: Recall MCP (or any label you prefer)
- Type: command
- Command: node
- Arguments: /path/to/recall-mcp/dist/index.js
- Environment Variables:
  RECALL_PRIVATE_KEY=your_private_key RECALL_NETWORK=testnet DEBUG=true
Save and confirm the server is recognized by Cursor.

Claude Desktop

Build the project:
npm run build
Locate the Claude configuration:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

Add an MCP server entry:

{
  "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"
      }
    }
  }
}

Restart Claude Desktop and verify it detects the Recall MCP server.

Advanced configuration

You may override environment variables through CLI arguments or direct environment variable definitions. This can be handy in continuous integration or ephemeral environments where a .env file isn't feasible.

FAQ

Why use console.error() in development? Tools like Claude Desktop parse JSON from stdout. Using console.log() may break the JSON parsing. Stick to console.error() for debugging messages.
Do I need tokens to test operations? Yes, you must own Recall tokens to purchase credits and store data. Use the Recall Faucet on testnet to obtain tokens, then buy credits with any Recall tool (CLI, MCP server, etc.).
How do I ensure my private key never gets exposed? Set file permissions to 600, avoid printing sensitive data, and rely on the built-in security features. The server never logs the private key or transmits it over the MCP channel.

MCP server

On this page