mcp-xrpl

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.

📋 Contents

• Overview
• Features
• Supported Networks
• Prerequisites
• Installation
• Server Configuration
• Usage
• API Reference
• Security Considerations
• Project Structure
• Development
• License

🔭 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

# 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:

# 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

# 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

XRP and Token Operations

NFT Operations

DID Operations

AMM Operations

Resources

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

Ledger Resources

Token Resources

🔒 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

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:

1. Create a new TypeScript file in the appropriate directory under src/transactions/
2. Import the server from server/server.js
3. Define the tool using server.tool()
4. 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.