UluWalletMCP

MCP server for managing Algorand signer records, enforcing local signing policy, and signing payloads.

Build anywhere, sign here.

UluWalletMCP is not responsible for network access, querying chain state, building transactions, or broadcasting. The caller handles chain context and payload correctness. UluWalletMCP handles key management, policy enforcement, and signing only.

Setup

npm install

Optionally set a custom data directory (defaults to ~/.ulu-wallet-mcp):

export ULU_WALLET_MCP_DATA_DIR=/path/to/data

Usage

node index.js

Adding to a Client

{
  "mcpServers": {
    "ulu-wallet-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ulu-wallet-mcp/index.js"]
    }
  }
}

Tools

Signer Management

| Tool | Description | |------|-------------| | wallet_list_signers | List all registered signers | | wallet_get_signer | Get full signer record by ID | | wallet_create_hot_signer | Generate a new hot signer with fresh keypair | | wallet_import_hot_signer | Import an account from a 25-word mnemonic | | wallet_create_lsig_signer | Create a LogicSig signer from compiled TEAL | | wallet_delete_signer | Delete a signer and its key material |

Signing

| Tool | Description | |------|-------------| | wallet_sign_transactions | Sign unsigned transactions with policy enforcement | | wallet_sign_bytes | Sign arbitrary bytes (hot signers only) |

Core Concepts

Signer Record

Each signer is a registered signing authority identified by signerId:

{
  "signerId": "agent-hot-1",
  "signerType": "hot",
  "signerClass": "custody",
  "storageType": "local_file",
  "capabilities": ["sign_transactions", "sign_bytes"],
  "metadata": {
    "description": "Agent automation signer",
    "nickname": "agent-hot",
    "createdAt": "2026-03-07T18:00:00Z"
  },
  "addresses": {
    "primary": "ADDRESS_HERE",
    "authAddress": null,
    "lsigAddress": null
  },
  "policy": {
    "maxTransactionsPerRequest": 16,
    "allowRekey": false,
    "allowCloseRemainderTo": false,
    "allowAssetCloseTo": false,
    "expiresAt": null
  },
  "config": {},
  "state": {}
}

Signer Types

| Type | Description | Use Cases | |------|-------------|-----------| | hot | Unattended local signer with key stored on disk | Automation, relays, fee sponsorship, agents | | lsig | Stored LogicSig signer (Algorand-specific) | Constrained delegated signing, time-limited authority | | secure | OS-keychain-backed signer (planned) | User custody, higher trust signing |

Signer Classes

| Class | Meaning | |-------|---------| | custody | Signer controls key material directly | | delegated | Constrained delegated authority (e.g. LogicSig) | | external | Signing performed by external system (planned) | | virtual | Identity-only record, no signing (planned) |

Storage Types

| Type | Used By | |------|---------| | local_file | Hot signers — secret key stored in ~/.ulu-wallet-mcp/keys/ | | artifact | LogicSig signers — serialized lsig stored in ~/.ulu-wallet-mcp/keys/ | | os_keychain | Secure signers (planned) |

Capabilities

| Capability | Description | |------------|-------------| | sign_transactions | Can sign Algorand transaction payloads | | sign_bytes | Can sign arbitrary byte arrays (hot signers only) |

Policy

Policy is enforced before every signing operation. Transactions violating policy are rejected.

| Field | Default | Description | |-------|---------|-------------| | maxTransactionsPerRequest | 16 | Max transactions per signing call | | allowRekey | false | Allow transactions with rekeyTo set | | allowCloseRemainderTo | false | Allow payment transactions that close the account | | allowAssetCloseTo | false | Allow asset transfers that close out the asset | | expiresAt | null | ISO 8601 expiry timestamp, null for no expiry |

Additionally, wallet_sign_transactions verifies that each transaction's sender address matches the signer's address before signing.

Data Directory

All persistent state lives under ~/.ulu-wallet-mcp/ (or $ULU_WALLET_MCP_DATA_DIR):

~/.ulu-wallet-mcp/
├── signers.json          # Signer records (0600)
└── keys/                 # Key material directory (0700)
    ├── <signerId>.key    # Hot signer secret keys (0600, base64)
    └── <signerId>.lsig   # Serialized LogicSig artifacts (0600, base64)

Key material files are created with restrictive permissions (0600/0700).