xrpl-mcp

An MCP server, @florent-uzio/xrpl-mcp, that lets an AI client such as Claude Code query and transact on the XRP Ledger. It runs over stdio and is built with Mastra and xrpl.js. See GLOSSARY.md for the vocabulary.

• Over 120 tools:
  • query the ledger (accounts, ledgers, transactions, order books, AMMs, NFTs, vaults, servers, fees)
  • submit the XRPL transaction types (payments, trust lines, DEX offers, AMMs, NFTs, MPTs, escrows, checks, payment channels, credentials, vaults, lending, oracles, batches, confidential MPTs)
  • create and fund wallets
  • convert units and currency codes
• 4 workflows for multi-step setups on test networks: IOU issuance, MPT issuance, confidential MPT and lending setup.

Use it from Claude Code

You only need Node.js 22.13 or later. No model API key is required: Claude Code does the reasoning and calls the tools.

claude mcp add xrpl -- npx -y @florent-uzio/xrpl-mcp@latest

Then ask Claude things like "What is the balance of rXXX on mainnet?" or "Issue an MPT on testnet with 2 holders".

@latest makes npx check npm each time Claude Code starts the server, so a new release loads in your next session, or when you reconnect xrpl from /mcp. To stay on one version, pin it instead, e.g. @florent-uzio/[email protected].

To run the server from a clone of this repo instead:

claude mcp add xrpl -- npm --prefix "$(pwd)" run --silent mcp

Networks and secrets

• Mainnet is the default. Say "testnet" or "devnet", or give a wss:// URL, to use another network. Every known network is listed in src/helpers/networks.ts.
• Seeds are refused outside test networks, before any connection is made. On mainnet, sign the transaction yourself and submit the blob with submitSignedBlob.
• Flow records keep what a session creates (wallets, MPT IDs, keys, hashes), so a later session can reuse it. saveFlowRecord refuses seeds and private keys on mainnet.

Workflows

The server exposes each workflow as run_<name>.

The input of each workflow is described in its schema, in src/workflows/*.types.ts.

Add a tool

Transaction tools use the factory. It adds network and seed, refuses seeds outside test networks, hex-encodes every currency code, then autofills, signs and submits the transaction:

// src/tools/transactions/payment/payment.ts
import { Payment } from 'xrpl'
import { useTransactionToolFactory } from '../factory'
import { xrplPaymentSchema } from './payment.types'

const { createTransactionTool } = useTransactionToolFactory({ inputSchema: xrplPaymentSchema })

export const submitPaymentTool = createTransactionTool<Payment>({
  toolId: 'submitPayment',
  description: 'Submit a Payment transaction to send XRP, tokens or MPTs. ...',
  // Optional: reshape the input into the transaction
  buildTransaction: payment => ({ ...payment, Amount: payment.DeliverMax ? undefined : payment.Amount }) as Payment,
  // Optional: throw to refuse the transaction before it is signed
  validateTransaction: params => {
    if (params.Amount === undefined && params.DeliverMax === undefined) {
      throw new Error('Provide Amount (API v1) or DeliverMax (API v2)')
    }
  },
})

Query tools use defineMethodTool (src/tools/methods/shared/method-tool.ts), with the id, the xrpld command and the request and result schemas.

Export the new tool from its folder's index.ts. src/catalog.ts picks up every tool exported from src/tools, so the server exposes it.

The server exposes each tool under its id, so the id is the name the model sees. Name the export after the id with a Tool suffix (submitPaymentTool for submitPayment): a test checks it. Never rename a published tool: it breaks every client that calls it (see docs/adr/0001-tool-names-are-camelcase-ids.md).

Development

npm test               # unit tests
npm run typecheck      # tsc
npm run format         # prettier
npm run build          # bundle the server into dist/

Domain terms are in GLOSSARY.md. Releases of the MCP package follow RELEASING.md.