# iExec MCP Server
> A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) compatible server to interact with the [iExec](https://iex.ec) protocol — built for Claude, agents, and AI tooling.
---
## 1. Wallet Setup
**Prerequisites:**
- [Node.js](https://nodejs.org/) (version 18 or higher)
- npm (version 9 or higher)
**Option 1: Create a new wallet with iExec**
```bash
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`:
```bash
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](#3-method-a-npx-configuration-for-claude-desktop)** ⭐ | Direct Claude Desktop setup | Quick Claude Desktop integration |
| **[4. Claude Code CLI](#4-method-b-claude-code-cli-setup)** | CLI integration setup | Developers using Claude Code |
| **[5. Local Node.js](#5-method-c-local-nodejs-setup)** | Development from source | Local development & debugging |
| **[6. Docker](#6-method-d-docker-setup)** | Containerized deployment | Production & isolated environments |
| **[7. Cursor IDE](#7-method-e-cursor-ide-setup)** | Cursor IDE integration | Developers using Cursor IDE |
---
## 3. Method A: NPX Configuration for Claude Desktop
**Prerequisites:**
- [Node.js](https://nodejs.org/) (version 18 or higher)
- npm (version 9 or higher)
- [Claude Desktop](https://claude.ai/download)
**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):_
```json
{
"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:_
```json
{
"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](https://nodejs.org/) (version 18 or higher)
- npm (version 9 or higher)
**Setup Steps:**
1. **Install Claude Code CLI:**
```bash
npm install -g @anthropic-ai/claude-code
```
2. **Add iExec MCP server:**
_With wallet file (from Section 1):_
```bash
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:_
```bash
claude mcp add iexec-mcp --env PRIVATE_KEY=0xYOUR_PRIVATE_KEY -- npx @iexec/mcp-server@latest iexec-mcp
```
3. **Run Claude:**
```bash
claude
```
---
## 5. Method C: Local Node.js Setup
**Prerequisites:**
- [Node.js](https://nodejs.org/) (version 18 or higher)
- npm (version 9 or higher)
- [Git](https://git-scm.com/)
- [Claude Desktop](https://claude.ai/download)
**Setup Steps:**
### 5.1. Clone, Install, and Build
```bash
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):_
```json
{
"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:_
```json
{
"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](https://www.docker.com/get-started) installed
- [Claude Desktop](https://claude.ai/download)
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):_
```json
{
"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:_
```json
{
"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](https://nodejs.org/) (version 18 or higher)
- npm (version 9 or higher)
- [Cursor](https://cursor.sh/) IDE installed
**Setup Steps:**
### 7.1. Install iExec MCP Server
```bash
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:
```json
{
"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:
```bash
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:
```json
{
"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`](./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](https://docs.iex.ec)
- [Join iExec on Discord](https://discord.iex.ec)
- [About MCP](https://modelcontextprotocol.io/introduction)
---
## 13. Contributing
Contributions welcome! Open an issue or PR to suggest improvements.
