iExec MCP Server

A Model Context Protocol (MCP) compatible server to interact with the iExec protocol — built for Claude, agents, and AI tooling.

---

1. Wallet Setup

Prerequisites:

• Node.js (version 18 or higher)
• npm (version 9 or higher)

Option 1: Create a new wallet with iExec

npm install -g iexec
iexec wallet create --unencrypted

Find your wallet at:

• Linux: ~/.ethereum/keystore/wallet.json
• macOS: ~/Library/Ethereum/keystore/wallet.json
• Windows: %APPDATA%/Ethereum/keystore/wallet.json

Option 2: Use an existing private key

• Create a wallet.json:

  mkdir -p ./my-wallet
  echo '{"privateKey":"0xYOUR_PRIVATE_KEY"}' > ./my-wallet/wallet.json

• Or use your raw private key directly in Claude configuration.

Important: All sensitive configuration (PRIVATE_KEY_PATH or PRIVATE_KEY) is used only at the local MCP server level and is never transmitted to Claude or any other AI model. This information remains strictly confidential on your local machine.

2. Getting Started

Complete the Wallet Setup above, then choose your preferred installation method:

Method	Description	Best For
3. NPX Configuration ⭐	Direct Claude Desktop setup	Quick Claude Desktop integration
4. Claude Code CLI	CLI integration setup	Developers using Claude Code
5. Local Node.js	Development from source	Local development & debugging
6. Docker	Containerized deployment	Production & isolated environments
7. Cursor IDE	Cursor IDE integration	Developers using Cursor IDE

---

3. Method A: NPX Configuration for Claude Desktop

Prerequisites:

• Node.js (version 18 or higher)
• npm (version 9 or higher)
• Claude Desktop

Setup Steps:

1. Open Claude Desktop configuration:

   • Open Claude Desktop → Developer > Edit Config

2. Add configuration to claude_desktop_config.json:

   With wallet file (from Section 1):

   {
     "mcpServers": {
       "iexec-mcp-server": {
         "command": "npx",
         "args": ["-y", "@iexec/mcp-server@latest"],
         "env": {
           "PRIVATE_KEY_PATH": "/ABSOLUTE/PATH/TO/YOUR/KEYSTORE/wallet.json"
         }
       }
     }
   }

   With direct private key:

   {
     "mcpServers": {
       "iexec-mcp-server": {
         "command": "npx",
         "args": ["-y", "@iexec/mcp-server@latest"],
         "env": {
           "PRIVATE_KEY": "0xYOUR_PRIVATE_KEY"
         }
       }
     }
   }

3. Restart Claude Desktop - You should see a plug icon for iexec-mcp-server

---

4. Method B: Claude Code CLI Setup

Prerequisites:

• Node.js (version 18 or higher)
• npm (version 9 or higher)

Setup Steps:

1. Install Claude Code CLI:

   npm install -g @anthropic-ai/claude-code

2. Add iExec MCP server:

   With wallet file (from Section 1):

   claude mcp add iexec-mcp --env PRIVATE_KEY_PATH=/ABSOLUTE/PATH/TO/YOUR/KEYSTORE/wallet.json -- npx @iexec/mcp-server@latest iexec-mcp

   With direct private key:

   claude mcp add iexec-mcp --env PRIVATE_KEY=0xYOUR_PRIVATE_KEY -- npx @iexec/mcp-server@latest iexec-mcp

3. Run Claude:

   claude

---

5. Method C: Local Node.js Setup

Prerequisites:

• Node.js (version 18 or higher)
• npm (version 9 or higher)
• Git
• Claude Desktop

Setup Steps:

5.1. Clone, Install, and Build

git clone https://github.com/iexecBlockchainComputing/iexec-mcp-server.git
cd iexec-mcp-server
npm install
npm run build

5.2. Integrate with Claude Desktop

1. Open Claude Desktop configuration:

   • Open Claude Desktop → Developer > Edit Config

2. Add configuration to claude_desktop_config.json:

   With wallet file (from Section 1):

   {
     "mcpServers": {
       "iexec-mcp-server": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO-IEXEC-MCP-SERVER-REPO/build/index.js"],
         "env": {
           "PRIVATE_KEY_PATH": "/ABSOLUTE/PATH/TO/wallet.json"
         }
       }
     }
   }

   With direct private key:

   {
     "mcpServers": {
       "iexec-mcp-server": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO-IEXEC-MCP-SERVER-REPO/build/index.js"],
         "env": {
           "PRIVATE_KEY": "0xYOUR_PRIVATE_KEY"
         }
       }
     }
   }

3. Restart Claude Desktop - You should see a plug icon for iexec-mcp-server

---

6. Method D: Docker Setup

Prerequisites:

• Docker installed
• Claude Desktop

1. Open Claude Desktop configuration:

• Open Claude Desktop → Developer > Edit Config

2. Add configuration to claude_desktop_config.json:

   With wallet file (from Section 1):

   {
     "mcpServers": {
       "iexec-mcp-server": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "--init",
           "-v",
           "/ABSOLUTE/PATH/TO/YOUR/KEYSTORE:/app/keystore",
           "-e",
           "PRIVATE_KEY_PATH=/app/keystore/wallet.json",
           "iexechub/mcp-server:latest"
         ]
       }
     }
   }

   With direct private key:

   {
     "mcpServers": {
       "iexec-mcp-server": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "--init",
           "-e",
           "PRIVATE_KEY=0xYOUR_PRIVATE_KEY",
           "iexechub/mcp-server:latest"
         ]
       }
     }
   }

3. Restart Claude Desktop - You should see a plug icon for iexec-mcp-server

---

7. Method E: Cursor IDE Setup

Prerequisites:

• Node.js (version 18 or higher)
• npm (version 9 or higher)
• Cursor IDE installed

Setup Steps:

7.1. Install iExec MCP Server

npm install -g @iexec/mcp-server

7.2. Configure Cursor

1. Open Cursor Settings:

   • Press Cmd+, (macOS) or Ctrl+, (Windows/Linux)
   • Or go to Cursor > Preferences > Settings

2. Search for "MCP" in settings:

   • Look for "Model Context Protocol" or "MCP" settings

3. Add MCP Server Configuration:

   Option A: Using Settings UI (if available):

   • Add a new MCP server entry
   • Set the command to: @iexec/mcp-server
   • Add environment variables:
     • PRIVATE_KEY_PATH: /ABSOLUTE/PATH/TO/YOUR/KEYSTORE/wallet.json
     • Or PRIVATE_KEY: 0xYOUR_PRIVATE_KEY

   Option B: Manual Configuration:

   • Open Cursor's configuration file (usually in user settings)
   • Add the following configuration:

   {
     "mcpServers": {
       "iexec-mcp-server": {
         "command": "npx",
         "args": ["-y", "@iexec/mcp-server@latest"],
         "env": {
           "PRIVATE_KEY_PATH": "/ABSOLUTE/PATH/TO/YOUR/KEYSTORE/wallet.json"
         }
       }
     }
   }

   Option C: Using Cursor's AI Features:

   • Open the AI chat panel in Cursor
   • Type: "Configure MCP server for iExec with private key path: /path/to/wallet.json"
   • Cursor should help you set up the configuration

4. Restart Cursor - The iExec MCP server should now be available in your AI interactions

7.3. Alternative: Local Development Setup

If you prefer to run from source:

git clone https://github.com/iexecBlockchainComputing/iexec-mcp-server.git
cd iexec-mcp-server
npm install
npm run build

Then configure Cursor to use the local build:

{
  "mcpServers": {
    "iexec-mcp-server": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO-IEXEC-MCP-SERVER-REPO/build/index.js"],
      "env": {
        "PRIVATE_KEY_PATH": "/ABSOLUTE/PATH/TO/wallet.json"
      }
    }
  }
}

---

9. Available Tools & API

• Confidential Data: protectData, getProtectedData, processProtectedData
• Data Governance: grantAccess, revokeOneAccess, revokeAllAccess, transferOwnership, getGrantedAccess
• Web3Mail: sendEmail, fetchMyContacts, fetchUserContacts
• Wallet & Resources: getUserVoucher, getWalletBalance, getIExecApps

Full API docs: TOOLS.md

---

10. Example Prompts

• "Please protect my email address alice@example.com with the name iexec-mcp-email-demo."
• "List all protected data tied to my wallet."
• "Grant access to protected data 0x123 for iExec app web3mail and user 0xUSER."
• "Revoke access to protected data 0x123 for app web3mail and user 0xUSER."
• "Revoke all access for protected data 0x123."
• "Transfer the ownership of protected data 0x123 to 0x456."
• "Send email to 0xrecipient with subject Update and message Access approved."
• "List all my Web3mail contacts."
• "What's my wallet balance on iExec?"
• "Do I have a user voucher?"
• "Run app 0xAPP on protected data 0xDATA."

---

11. Security & Best Practices

• For production, use PRIVATE_KEY_PATH and keep your wallet file secure.
• Never commit your private key or wallet file to source control.
• The server runs locally; your private key is never sent externally.
• Claude and other agents never access your key or raw data.

---

12. Help & Resources

• iExec Developer Docs
• Join iExec on Discord
• About MCP

---

13. Contributing

Contributions welcome! Open an issue or PR to suggest improvements.