# execution-run-mcp

Model Context Protocol (MCP) server for the [Execute.run](https://execution.run) bot API. Enables AI agents to manage Shell balances, transfer funds, and execute LLM requests through the Execute.run platform.

## Installation

### Via npx (Recommended)

```bash
npx @execution-run/mcp-server
```

### Via npm

```bash
npm install -g @execution-run/mcp-server
execution-run-mcp
```

### From Source

```bash
git clone https://github.com/execution-run/execution-run-mcp.git
cd execution-run-mcp
bun install
bun run build
```

## Configuration

Set the following environment variables:

- `EXECUTE_RUN_API_KEY` (required): Your Execute.run API key from [execution.run/api-keys](https://execution.run/api-keys)
- `EXECUTE_RUN_API_URL` (optional): API base URL (defaults to `https://execution.run/v1`)

## Usage

### With Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "execution-run": {
      "command": "npx",
      "args": ["execution-run-mcp"],
      "env": {
        "EXECUTE_RUN_API_KEY": "sk_live_your_api_key_here"
      }
    }
  }
}
```

### With Kiro

Add to your `.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "execution-run": {
      "command": "npx",
      "args": ["execution-run-mcp"],
      "env": {
        "EXECUTE_RUN_API_KEY": "sk_live_your_api_key_here"
      }
    }
  }
}
```

### Standalone

```bash
EXECUTE_RUN_API_KEY=sk_live_xxx execution-run-mcp
```

## Available Tools

### whoami

Get your card and wallet identity information.

**Parameters:** None

**Returns:**
```json
{
  "cardId": "crd_abc123",
  "walletId": "exe_xyz789",
  "address": "bot-prod@exe_xyz789",
  "balance": 1000,
  "status": "active"
}
```

### get_balance

Get the current Shell balance and ceiling for your wallet.

**Parameters:** None

**Returns:**
```json
{
  "balance": 1000,
  "ceiling": 1000000
}
```

### get_transactions

Get transaction history for your wallet.

**Parameters:**
- `limit` (optional): Number of transactions to return (default: 50, max: 100)

**Returns:**
```json
{
  "transactions": [
    {
      "id": "tx_123",
      "type": "mint",
      "amount": 1000,
      "balanceAfter": 1000,
      "timestamp": { "_seconds": 1706745600 },
      "purpose": "Initial credit"
    }
  ]
}
```

### transfer

Transfer Shells to another wallet.

**Parameters:**
- `to` (required): Recipient wallet ID (exe_xxx) or card address (cardName@exe_xxx)
- `amount` (required): Amount of Shells to transfer (positive integer)
- `purpose` (required): Purpose/context for the transfer

**Returns:**
```json
{
  "transaction": {
    "id": "tx_456",
    "type": "transfer",
    "amount": 100,
    "balanceAfter": 900,
    "purpose": "Payment for service"
  }
}
```

### sign

Sign a challenge with your card's Ed25519 keypair.

**Parameters:**
- `challenge` (required): Base64-encoded challenge to sign

**Returns:**
```json
{
  "signature": "base64_encoded_signature",
  "cardId": "crd_abc123",
  "walletId": "exe_xyz789"
}
```

### compute

Execute an LLM request by burning Shells.

**Parameters:**
- `model` (required): Model identifier (e.g., 'gemini-2.0-flash', 'gpt-4o', 'claude-3-5-sonnet-latest')
- `messages` (required): Array of conversation messages with `role` and `content`
- `temperature` (optional): Sampling temperature (0-2)
- `maxTokens` (optional): Maximum tokens to generate

**Returns:**
```json
{
  "content": "Hello! How can I help you?",
  "model": "gemini-2.0-flash",
  "cost": 4
}
```

## Development

```bash
# Install dependencies
bun install

# Build
bun run build

# Watch mode
bun run dev

# Run locally
bun run start
```

## License

MIT

## Links

- [Execute.run Platform](https://execution.run)
- [API Documentation](https://execution.run/docs/api)
- [Get API Key](https://execution.run/api-keys)
- [Model Context Protocol](https://modelcontextprotocol.io)