home / mcp / iexec mcp server

iExec MCP Server

Provides an MCP server to interact with the iexec protocol using private keys or keystore wallets for secure data governance and protected data operations.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You run the iExec MCP Server to interact with the iExec protocol through a self-hosted MCP endpoint. It lets you manage wallets, protect data, grant access, and run iExec-enabled applications from your local environment or within containers, while keeping sensitive keys securely on your host machine.

How to use

You use an MCP client to connect to the iExec MCP Server either locally (stdio) or via a remote HTTP endpoint. Start the MCP server with a locally configured wallet (private key or wallet file) and then configure your MCP client to point to that server. The server exposes tools for wallet management, data protection, access control, and app interaction, all through the MCP interface.

How to install

Prerequisites: Node.js 18+ and npm 9+. These are required for all installation methods.

Choose one installation method and follow the concrete steps below.

Method A: NPX Configuration for Claude Desktop

Prerequisites: Node.js 18+ and npm 9+. Claude Desktop.

1. Open Claude Desktop configuration and add a MCP server entry that uses npx to launch the MCP server.

2. Use wallet file configuration (wallet.json) by setting PRIVATE_KEY_PATH to the absolute path of your wallet file.

3. Or use a direct private key by setting PRIVATE_KEY to your private key value.

4. Restart Claude Desktop to recognize the new MCP server entry.

Method B: Claude Code CLI Setup

Prerequisites: Node.js 18+ and npm 9+.

1. Install the Claude Code CLI globally.

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

2. Add the iExec MCP server using either a wallet file or a private key.

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

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

3. Run Claude to start using the MCP server.

Method C: Local Node.js Setup

Prerequisites: Node.js 18+, npm 9+, Git, and Claude Desktop.

5.1. Clone, install dependencies, and build the MCP server.

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 by configuring the MCP server entry to run the built index.js.

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

Method D: Docker Setup

Prerequisites: Docker installed and Claude Desktop.

1. Open Claude Desktop and add a MCP server entry that runs the MCP server inside Docker.

2. Use a wallet file by mounting your keystore and setting PRIVATE_KEY_PATH to the mounted path.

3. Or set PRIVATE_KEY with your private key string.

3. Restart Claude Desktop to recognize the new MCP server entry.

Example run configuration when using wallet file (mounting the keystore):
```
{
  "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"
      ]
    }
  }
}

Method E: Cursor IDE Setup

Prerequisites: Node.js 18+ and npm 9+; Cursor IDE installed.

7.1 Install the MCP server globally.

npm install -g @iexec/mcp-server

7.2 Configure Cursor by adding an MCP server with either a wallet path or a private key.

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

7.3 Alternative: manual Cursor configuration in settings.

7.3.1 Open Cursor Settings and search for MCP. Add a server entry with command npx and arguments -y @iexec/mcp-server@latest, and an environment variable for PRIVATE_KEY_PATH or PRIVATE_KEY.

7.3.2 Restart Cursor to enable the MCP server.

7. Alternative: Local development setup

If you prefer running from source, clone, install, and build, then point your MCP client to the local build.

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

Configure Cursor to use the local build by setting the MCP server to run the built index.

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

The MCP server provides a set of tools to handle confidential data and access control, including data protection, access grants, and wallet-related queries. Specifically, you can call tools for protecting data, retrieving protected data, transferring ownership, and sending communications via Web3Mail, among others.

10. Example Prompts

Ask the MCP server to protect an email address, manage access, or send a notification using the provided tools.

11. Security & Best Practices

Use PRIVATE_KEY_PATH for production to keep your wallet file secure. Do not commit your wallet file or private keys to any version control. The server runs locally, so your private key stays on your machine and is not shared with Claude or other AI models.

12. Help & Resources

Access iExec developer resources, join their Discord community, and learn more about MCP to maximize your usage.

13. Contributing

Contributions are welcome. Open issues or pull requests to suggest improvements.

Available tools

protectData

Protects data so it can be securely shared with authorized entities within the MCP framework.

getProtectedData

Retrieves data that has been protected by the MCP system, enforcing access controls.

processProtectedData

Processes protected data under defined governance and policy rules.

grantAccess

Grants access to protected data for specified apps or users.

revokeOneAccess

Revokes access to protected data for a specific app or user.

revokeAllAccess

Revokes all access to a protected data item.

transferOwnership

Transfers ownership of protected data to another user or entity.

getGrantedAccess

Queries which entities have been granted access to protected data.

sendEmail

Sends emails via Web3Mail related capabilities.

fetchMyContacts

Fetches the contacts associated with your Web3Mail account.

fetchUserContacts

Fetches contacts for a specific user within Web3Mail.

getUserVoucher

Retrieves user vouchers tied to wallet or account.

getWalletBalance

Checks the balance of the user wallet on iExec.

getIExecApps

Lists iExec applications available to the user.