npm package: @narval-xyz/litewallet-mcp
Description: MCP server for Litewallet — wallet control plane for AI Agents
Latest version: 0.0.10

# @narval-xyz/litewallet-mcp

MCP server for [Litewallet](https://litewallet.ai) — gives any AI assistant the ability to manage crypto wallets, transfer tokens, sign messages, and interact with blockchain networks.

Runs locally over **stdio** transport.

## Quick Start

Add this to your MCP client config:

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "litewallet": {
      "command": "npx",
      "args": ["-y", "@narval-xyz/litewallet-mcp"]
    }
  }
}
```

**Claude Code** (`~/.claude/settings.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "litewallet": {
      "command": "npx",
      "args": ["-y", "@narval-xyz/litewallet-mcp"]
    }
  }
}
```

To auto-approve all Litewallet tools (avoids permission prompts), add this to your `.claude/settings.json` or `.claude/settings.local.json`:

```json
{
  "permissions": {
    "allow": ["mcp__litewallet__*"]
  }
}
```

**Cursor** (Settings > MCP Servers):

```json
{
  "litewallet": {
    "command": "npx",
    "args": ["-y", "@narval-xyz/litewallet-mcp"]
  }
}
```

That's it. No global install needed — `npx` fetches and runs it on demand.

## Prerequisites

- Node.js >= 18
- A Narval Litewallet account

## Authentication

On first use, ask the assistant to authenticate:

> "Connect my Narval wallet"

This triggers `auth_init`, which returns a browser URL. Visit it to complete OAuth, then the assistant polls `auth_check` until the flow completes.

## Available Tools

### Auth

| Tool          | Description                                                                             |
| ------------- | --------------------------------------------------------------------------------------- |
| `auth_init`   | Start a Wallet Connection auth flow. Returns a redirect URL to complete in the browser. |
| `auth_check`  | Poll the status of a pending authentication flow.                                       |
| `auth_revoke` | Revoke the current access token permanently.                                            |

### Accounts & Config

| Tool             | Description                                           |
| ---------------- | ----------------------------------------------------- |
| `list_accounts`  | List all wallet accounts (address, network, default). |
| `switch_account` | Switch the active account by index or address.        |

### Balances & Networks

| Tool            | Description                                         |
| --------------- | --------------------------------------------------- |
| `get_balances`  | Fetch live on-chain token balances with USD prices. |
| `list_networks` | List all supported blockchain networks.             |

### Transactions

| Tool                 | Description                                                     |
| -------------------- | --------------------------------------------------------------- |
| `transfer`           | Transfer tokens (e.g. USDC, ETH) to a destination address.      |
| `send_transaction`   | Send a raw transaction with explicit parameters.                |
| `fetch_transaction`  | Fetch a transaction by ID to check its status.                  |
| `decode_transaction` | Decode a transaction to preview what it will do before sending. |

### DeFi & Trading

| Tool             | Description                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------- |
| `yield_list`     | List available yield vaults (Aave, Morpho) with APY, TVL, and filters.                   |
| `yield_deposit`  | Deposit tokens into a yield vault. Fails with INSUFFICIENT_ALLOWANCE if approval needed. |
| `yield_withdraw` | Withdraw tokens from a yield vault.                                                      |
| `swap`           | Swap tokens on the same chain. Fails with INSUFFICIENT_ALLOWANCE if approval needed.     |
| `bridge`         | Bridge tokens cross-chain. Fails with INSUFFICIENT_ALLOWANCE if approval needed.         |
| `quote`          | Get a swap/bridge quote (read-only).                                                     |
| `approve`        | Approve ERC-20 token spending for a spender address. Supports dry-run.                   |

### Signing

| Tool              | Description                          |
| ----------------- | ------------------------------------ |
| `personal_sign`   | Sign a plain text message (EIP-191). |
| `sign_typed_data` | Sign EIP-712 typed data.             |

## Examples

**Check balances:**

> "What are my token balances across all chains?"

**Transfer tokens:**

> "Send 10 USDC to 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 on Ethereum"

**Sign a message:**

> "Sign the message 'Hello World' with my wallet"

**Approve a spender:**

> "Approve Uniswap router to spend 100 USDC"

**Deposit into a vault:**

> "Deposit 100 USDC into the best Morpho vault on Base"

**Swap tokens:**

> "Swap 50 USDC for WETH on Base"

**Bridge tokens:**

> "Bridge 100 USDC from Ethereum to Base"

**Check transaction status:**

> "What's the status of my last transaction?"

## Development

```bash
# Build
npx nx build litewallet-mcp

# Output
dist/packages/litewallet-mcp/
```

## License

See repository root.