# 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)
