xrpl-mcp-server

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

| 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

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.