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