XRP Ledger Model Context Protocol Server

License: MIT | XRPL Networks | TypeScript | xrpl.js

A comprehensive Model Context Protocol (MCP) server that provides blockchain services for the XRP Ledger ecosystem. This server enables AI agents to interact with XRPL MainNet, TestNet, and DevNet with a unified interface.

🔭 Overview

The MCP XRPL Server leverages the Model Context Protocol to provide XRP Ledger services to AI agents. It supports a wide range of services including:

Reading ledger state (balances, transactions, account info, etc.)
Interacting with smart contracts (via Hooks)
Transferring XRP and issued tokens
Querying token metadata and balances
Managing decentralized identifiers (DIDs)
Working with NFTs on the XRPL
Automated Market Maker (AMM) operations
Payment channels, escrows, and checks
Oracle data operations
Trustline management

All services are exposed through a consistent interface of MCP tools and resources, making it easy for AI agents to discover and use XRPL functionality.

✨ Features

Account Management

Connect to XRPL networks (MainNet, TestNet, DevNet)
Account information retrieval
Account property management
Deposit preauthorization
Regular key management

XRP and Token Operations

Transfer XRP between accounts
Get token metadata (name, symbol, decimals, supply)
Check token balances
Transfer tokens between addresses
Approve token spending
Token clawback

NFT Operations

Mint NFTs on the XRP Ledger
View NFT metadata
Verify NFT ownership
Transfer NFTs between addresses
Get NFT collections

Decentralized Identifier (DID)

Create DIDs on the XRPL
Resolve DIDs
Update DID documents
Deactivate DIDs

AMM Operations

Create Automated Market Makers
Deposit to AMMs
Place bids on AMMs
Vote on AMM parameters
Delete AMMs
Clawback assets from AMMs

Check Operations

Create checks
Cash checks
Cancel checks

Offer/DEX Operations

Create offers
Cancel offers

Oracle Operations

Set oracle data
Delete oracle data

Payment Channels

Create payment channels
Fund payment channels
Claim from payment channels

Escrow

Create escrows
Finish escrows
Cancel escrows

Trustlines

Set and manage trustlines

Ticketing

Create tickets for transaction processing

🌐 Supported Networks

MainNet: Production XRP Ledger network
TestNet: Test network for development
DevNet: Development network for experimental features

🛠️ Prerequisites

Node.js 18.0.0 or higher

📦 Installation

bash

# Clone the repository
git clone https://github.com/yourusername/mcp-xrpl.git
cd mcp-xrpl

# Install dependencies
npm install

# Build the project
npm run build

⚙️ Server Configuration

Create a .env file in the project root with the following variables:

Code

# Optional: XRPL wallet seed for automatic connection
# If not provided, you can connect using the connect-to-xrpl tool
DEFAULT_SEED=sEdVoKkRRF8RsNYZ689NDeMyrijiCbg  # Example - replace with your own or remove

# Network selection (default is "testnet")
XRPL_NETWORK=testnet  # Options: mainnet, testnet, devnet

🚀 Usage

Starting the Server

bash

# Start the server in stdio mode (for CLI tools)
npm start

Connecting to the Server

Connect to this MCP server using any MCP-compatible client. For testing and debugging, you can use the MCP Inspector.

📚 API Reference

Tools

The server provides the following MCP tools for agents:

Account Management

Tool Name	Description	Key Parameters
`connect-to-xrpl`	Connect to XRP Ledger using a seed	seed, network
`get-account-info`	Get account information	address, network
`delete-account`	Delete an XRPL account	privateKey, destination, network
`set-account-properties`	Set account properties	privateKey, properties, network
`deposit-preauth`	Preauthorize a deposit	privateKey, authorize, network
`set-regular-key`	Set a regular key for an account	privateKey, regularKey, network

XRP and Token Operations

Tool Name	Description	Key Parameters
`transfer-xrp`	Send XRP to an account	privateKey, to, amount, network
`get-token-metadata`	Get token metadata	tokenAddress, network
`check-token-balance`	Check token balance	tokenAddress, ownerAddress, network
`transfer-token`	Transfer tokens	privateKey, tokenAddress, to, amount, network
`approve-token-spending`	Approve token spending	privateKey, tokenAddress, limit, network
`token-clawback`	Clawback tokens	privateKey, tokenAddress, from, amount, network

NFT Operations

Tool Name	Description	Key Parameters
`nft-mint`	Mint an NFT	privateKey, uri, flags, network
`get-nft-info`	Get NFT metadata	tokenID, network
`check-nft-ownership`	Verify NFT ownership	tokenID, ownerAddress, network
`transfer-nft`	Transfer an NFT	privateKey, tokenID, to, network
`get-nft-collection`	Get NFTs in a collection	address, network

DID Operations

Tool Name	Description	Key Parameters
`create-did`	Create a DID	privateKey, data, network
`resolve-did`	Resolve a DID	did, network
`update-did`	Update a DID	privateKey, did, data, network
`deactivate-did`	Deactivate a DID	privateKey, did, network

AMM Operations

Tool Name	Description	Key Parameters
`amm-create`	Create an AMM	privateKey, assets, network
`amm-deposit`	Deposit to an AMM	privateKey, ammID, assets, network
`amm-bid`	Place bid on an AMM	privateKey, ammID, bid, network
`amm-vote`	Vote on AMM parameters	privateKey, ammID, vote, network
`amm-delete`	Delete an AMM	privateKey, ammID, network
`amm-clawback`	Clawback assets from AMM	privateKey, ammID, assets, network

Resources

The server exposes XRPL data through the following MCP resource URIs:

Ledger Resources

Resource URI Pattern	Description
`xrpl://{network}/ledger/current`	Current ledger information
`xrpl://{network}/ledger/{ledger_index}`	Ledger by index
`xrpl://{network}/account/{address}`	Account information
`xrpl://{network}/account/{address}/balance`	Account XRP balance
`xrpl://{network}/tx/{tx_hash}`	Transaction details

Token Resources

Resource URI Pattern	Description
`xrpl://{network}/token/{currency}/{issuer}`	Token information
`xrpl://{network}/token/{currency}/{issuer}/balanceOf/{address}`	Token balance
`xrpl://{network}/nft/{tokenID}`	NFT information
`xrpl://{network}/nft/{tokenID}/owner`	NFT ownership information

🔒 Security Considerations

Wallet seeds are used only for transaction signing and should be kept secure
Consider implementing additional authentication mechanisms for production use
For high-value services, consider adding confirmation steps
Default operations are performed on TestNet to ensure safety during development
Use environment variables for sensitive configuration

📁 Project Structure

Code

mcp-xrpl/
├── src/
│   ├── core/                # Core utilities and services
│   │   ├── constants.ts     # XRPL network URLs and other constants
│   │   ├── state.ts         # State management for connected wallet
│   │   ├── utils.ts         # Helper functions
│   │   └── services/        # Service modules
│   ├── server/              # MCP server implementation
│   ├── transactions/        # XRPL transaction implementation
│   │   ├── token/           # Token-related transactions
│   │   ├── nft/             # NFT-related transactions
│   │   ├── did/             # DID-related transactions
│   │   ├── amm/             # AMM-related transactions
│   │   ├── check/           # Check-related transactions
│   │   ├── offer/           # Offer-related transactions
│   │   ├── oracle/          # Oracle-related transactions
│   │   ├── payment/         # Payment-related transactions
│   │   ├── escrow/          # Escrow-related transactions
│   │   └── trust/           # Trust line-related transactions
│   └── index.ts             # Entry point
├── build/                   # Compiled JavaScript output
├── package.json
├── package-lock.json
└── tsconfig.json

🛠️ Development

Adding New Tools

To add a new tool:

Create a new TypeScript file in the appropriate directory under src/transactions/
Import the server from server/server.js
Define the tool using server.tool()
Import the tool in src/index.ts

Project Dependencies

@modelcontextprotocol/sdk: MCP SDK
xrpl: XRP Ledger JavaScript/TypeScript API
dotenv: Environment variable management
zod: TypeScript-first schema declaration and validation

📄 License

This project is licensed under the terms of the MIT License.

⚠️ Disclaimer

This software is provided for educational and development purposes only. Use it at your own risk. Always test thoroughly on the Testnet before using on Mainnet with real XRP.