XRP Ledger Testnet MCP Server

✅ MBSS v3.0 Compliant - A comprehensive Model Context Protocol (MCP) server for XRP Ledger (XRPL) testnet integration with AI systems.

🎯 Quick Overview

• Tool Count: 52 tools (25 MBSS mandatory + 27 XRP-specific)

• Network: XRP Ledger Testnet (testnet-only server)

• Architecture: MBSS v3.0 Unified Standard compliant

• Test Coverage: 95%+ enforced with security & chaos testing

• Help System: Interactive tool discovery and guidance

• Performance: Production-ready with proper error handling

⚠️ Testnet Focus - Server is locked to XRP Ledger Testnet for safe development and testing.

Related MCP server: XRPL MCP Server

🏗️ Server Architecture

graph TB
    A[AI Assistant] --> B[MCP Server]
    B --> C[XRP Ledger Client]
    C --> D[XRP Ledger Node]
    B --> E[Help System]
    B --> F[Tool Registry]
    E --> G[Tool Discovery]
    F --> H[Tool Execution]

    subgraph "Core Components"
        B
        E
        F
    end

    subgraph "External Services"
        C
        D
        G
        H
    end

Component Legend:

• MCP Server: Main server handling MCP protocol

• XRP Ledger Client: XRPL network interaction via WebSocket

• XRP Ledger Node: Blockchain node for data queries

• Help System: Interactive tool discovery and guidance

• Tool Registry: Centralized tool metadata management

✨ Key Features

🔗 Core XRP Ledger Operations

• Chain Information - Network statistics, health, and configuration details

• Balance Queries - XRP balances with formatted and raw values

• Transaction Lookup - Detailed transaction analysis with fee data

• Block Information - Ledger data with transaction counts and timestamps

• Address Validation - Format validation and network verification

💼 Wallet Management

• Wallet Creation - Generate new wallets (development/testing only)

• Wallet Import - Import from seed phrases or keys

• Account Information - Comprehensive wallet details and settings

• Balance Monitoring - Real-time balance tracking

🪙 Payment & DEX Operations

• XRP Payments - Send XRP with path finding and fee estimation

• DEX Trading - Order book management and trade execution

• Fee Estimation - Smart fee calculation for different transaction types

• Testnet Funding - Automated test XRP requests for development

AMM Operations (1 tool)

• xrp_get_amm_info - Query AMM pool details ✅

Token/Currency Operations (4 tools)

• xrp_create_trustline - Establish trust line for token ✅

• xrp_remove_trustline - Remove trust line (set limit to 0) ✅

• xrp_get_trustlines - Get all trustlines for account ✅

• xrp_send_token - Send issued tokens ✅

Escrow Operations (4 tools)

• xrp_create_escrow - Create time/conditional escrow ✅

• xrp_finish_escrow - Complete escrow with fulfillment ✅

• xrp_cancel_escrow - Cancel expired escrow ✅

• xrp_get_escrows - List account escrows ✅

NFT Operations (6 tools)

• xrp_mint_nft - Create NFT (basic) ✅

• xrp_mint_nft_with_ipfs - Create NFT with IPFS storage (Pinata/Web3.Storage) ✅ 🆕

• xrp_burn_nft - Destroy NFT ✅

• xrp_create_nft_offer - Create sell/buy offers ✅

• xrp_accept_nft_offer - Accept NFT offer ✅

• xrp_get_nfts - List account NFTs ✅

AI & Assistant Utilities (2 tools)

• xrp_get_conversation_guidance - Contextual prompts for guided agent flows ✅

• xrp_generate_nft_image - IPFS-ready image generation helper for NFT minting ✅

Network & Ledger Operations (7 tools)

• xrp_get_ledger - Ledger information ✅

• xrp_get_transaction - Transaction details ✅

• xrp_get_server_info - Network status ✅

• xrp_get_ledger_entry - Get specific ledger entry ✅

• xrp_get_account_objects - Get account-owned objects ✅

• xrp_subscribe - Real-time ledger updates ✅

• xrp_decode_transaction - Decode transaction blob ✅

Implementation Status

• ✅ 40 tools fully implemented and tested

• 🚀 All core XRPL features supported

• 📝 Complete with examples and documentation

🚀 Installation

Prerequisites

• Node.js: v18.0.0 or higher

• npm: Latest stable version

• Git: For cloning repository

Quick Start

# Clone the repository
git clone https://github.com/your-repo/xrp-testnet-mcp-server.git
cd xrp-testnet-mcp-server

# Install dependencies
npm install

# Build the server
npm run build

# Run with MCP Inspector for testing
npm run inspect

Configuration

Create a .env file in the root directory:

# Network Configuration
XRP_NETWORK=testnet
RPC_URL=wss://s.altnet.rippletest.net:51233
CHAIN_ID=NA

# Optional: IPFS configuration for NFT operations
PINATA_API_KEY=your_pinata_api_key
PINATA_SECRET_KEY=your_pinata_secret_key
IPFS_SERVICE=pinata

MCP Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "xrp-testnet": {
      "command": "node",
      "args": ["/path/to/xrp-testnet-mcp-server/dist/index.js"],
      "cwd": "/path/to/xrp-testnet-mcp-server",
      "env": {
        "XRP_NETWORK": "testnet"
      }
    }
  }
}

Docker Support

# Build Docker image
docker build -t xrp-testnet-mcp-server .

# Run container
docker run -p 3000:3000 xrp-testnet-mcp-server

📖 Usage Examples

Basic Operations

Get Network Information

{
  "tool": "xrp_get_chain_info",
  "arguments": {}
}

Check Balance

{
  "tool": "xrp_get_balance",
  "arguments": {
    "address": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH"
  }
}

Create Wallet (Development Only)

{
  "tool": "xrp_create_wallet",
  "arguments": {}
}

Advanced Workflows

Complete Transaction Flow

1. Check balance:

{
  "tool": "xrp_get_balance",
  "arguments": {
    "address": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH"
  }
}

2. Send payment:

{
  "tool": "xrp_send_transaction",
  "arguments": {
    "to": "rB7ASwFaJ2ryXUDUN8ViiVWba1ikXcqFxB",
    "amount": "10",
    "seed": "your_wallet_seed"
  }
}

AI Integration Examples

Claude Desktop Integration

{
  "tool": "xrp_help",
  "arguments": {
    "topic": "balance_queries"
  }
}

Tool Discovery

{
  "tool": "xrp_search_tools",
  "arguments": {
    "query": "balance"
  }
}

🛠️ Complete Tool Reference

MBSS v3.0 Core Tools (25 Mandatory)

1. xrp_get_chain_info

Get comprehensive XRP Ledger network information.

Purpose: Network health, statistics, and configuration details

Parameters: None

Returns:

{
  "network": "string",
  "ledgerVersion": "number",
  "fee": "string",
  "reserves": "object",
  "validatedLedger": "object",
  "serverInfo": "object"
}

2. xrp_get_balance

Get XRP balance for an address.

Purpose: Query account balances with formatted and raw values

Parameters:

• address (string, required): XRP Ledger address

Returns:

{
  "address": "string",
  "balance": "string",
  "balanceRaw": "string",
  "symbol": "XRP",
  "reserves": "string"
}

3. xrp_get_transaction

Get detailed transaction information by hash.

Purpose: Transaction analysis with fee and validation data

Parameters:

• hash (string, required): Transaction hash

Returns:

{
  "hash": "string",
  "validated": "boolean",
  "ledgerIndex": "number",
  "account": "string",
  "destination": "string",
  "amount": "string",
  "fee": "string",
  "meta": "object"
}

XRP-Specific Tools (29 Additional)

NFT Operations (6 tools)

• xrp_mint_nft: Create basic NFT

• xrp_mint_nft_with_ipfs: Create NFT with IPFS storage

• xrp_burn_nft: Destroy NFT

• xrp_create_nft_offer: Create sell/buy offers

• xrp_accept_nft_offer: Accept NFT offer

• xrp_get_nfts: List account NFTs

Token/Currency Operations (4 tools)

• xrp_create_trustline: Establish trust line for token

• xrp_remove_trustline: Remove trust line

• xrp_get_trustlines: Get all trustlines for account

• xrp_send_token: Send issued tokens

Escrow Operations (4 tools)

• xrp_create_escrow: Create time/conditional escrow

• xrp_finish_escrow: Complete escrow with fulfillment

• xrp_cancel_escrow: Cancel expired escrow

• xrp_get_escrows: List account escrows

DEX & AMM Operations (5 tools)

• xrp_place_order: Create buy/sell orders

• xrp_cancel_order: Cancel existing orders

• xrp_get_orderbook: Get order book data

• xrp_get_order_history: Get trading history

• xrp_get_amm_info: Query AMM pool details

Network & Ledger Operations (7 tools)

• xrp_get_ledger: Ledger information

• xrp_get_server_info: Network status

• xrp_get_ledger_entry: Get specific ledger entry

• xrp_get_account_objects: Get account-owned objects

• xrp_subscribe: Real-time ledger updates

• xrp_decode_transaction: Decode transaction blob

• xrp_request_faucet: Request testnet XRP

AI & Assistant Utilities (2 tools)

• xrp_get_conversation_guidance: Contextual prompts for guided flows

• xrp_generate_nft_image: IPFS-ready image generation helper

Account & Wallet Management (1 additional)

• xrp_get_account_info: Comprehensive account details

🌐 Supported Networks

Primary Network

• XRP Ledger Testnet (Chain ID: N/A)

  • Purpose: Primary XRP Ledger test network for development and testing

  • Block Time: ~3-5 seconds

  • Consensus: Ripple Protocol Consensus Algorithm (RPCA)

  • Native Token: XRP (Ripple)

Additional Networks

• XRP Ledger Devnet: Alternative testing network with controlled features

Testnet Faucets

• Official XRPL Faucet: https://faucet.altnet.rippletest.net/

• XRPL Dev Portal: https://xrpl.org/xrp-testnet-faucet.html

RPC Endpoints

• Primary: wss://s.altnet.rippletest.net:51233

• Backup: wss://testnet.xrpl-labs.com

• WebSocket: wss://s.altnet.rippletest.net:51233

Environment Variables

• XRP_NETWORK - Set to testnet or devnet (defaults to testnet)

• PINATA_API_KEY - Pinata API key for IPFS uploads

• PINATA_SECRET_KEY - Pinata secret key for IPFS uploads

• IPFS_SERVICE - IPFS service to use (pinata | web3Storage | nftStorage)

Testnet Resources

• Testnet Explorer: https://testnet.xrpl.org/

• Testnet WebSocket: wss://s.altnet.rippletest.net:51233

• Devnet Explorer: https://devnet.xrpl.org/

• XRPL Dev Tools: https://xrpl.org/dev-tools.html

IPFS Integration for NFTs 🆕

The server now supports decentralized NFT storage via IPFS using Pinata, Web3.Storage, or NFT.Storage.

Setting up IPFS Storage

1. Get a Pinata Account (Recommended)

   • Sign up at pinata.cloud

   • Get 1GB free storage (50% off with code NFTSTORAGE50)

   • Create API keys in dashboard

2. Configure Environment

   # .env file
   PINATA_API_KEY=your_api_key
   PINATA_SECRET_KEY=your_secret_key
   IPFS_SERVICE=pinata

3. Use the Enhanced NFT Tool

   // Tool #37: xrp_mint_nft_with_ipfs
   {
     "seed": "your_wallet_seed",
     "name": "My NFT",
     "description": "NFT with IPFS storage",
     "imageUrl": "https://example.com/image.jpg",
     "attributes": [
       { "trait_type": "Rarity", "value": "Legendary" }
     ],
     "flags": 8,  // 8 = transferable
     "transferFee": 1000  // 1% royalty
   }

IPFS Benefits

• ✅ Permanent, decentralized storage

• ✅ No single point of failure

• ✅ Content-addressed (tamper-proof)

• ✅ Globally accessible via any IPFS gateway

• ✅ Metadata and images stored separately

Conversational Usage Examples

Example 1: Quick NFT with Stock Image

User: "Create an NFT called 'Majestic Eagle' with a bald eagle image"

Assistant: "I'll create that NFT for you. Let me use a stock image of a bald eagle:"

// Uses Unsplash or similar stock photo
await xrp_mint_nft_with_ipfs({
  seed: "your_wallet_seed",
  name: "Majestic Eagle",
  description: "A powerful bald eagle soaring through the sky",
  imageUrl: "https://images.unsplash.com/photo-[eagle-id]",
  attributes: [
    { trait_type: "Species", value: "Bald Eagle" },
    { trait_type: "Rarity", value: "Legendary" }
  ]
})

Example 2: NFT with Your Own Image

User: "I have an image at https://mysite.com/art.jpg - make it an NFT with cool metadata"

Assistant: "I'll mint that as an NFT with enhanced metadata:"

await xrp_mint_nft_with_ipfs({
  seed: "your_wallet_seed",
  name: "Custom Artwork",
  imageUrl: "https://mysite.com/art.jpg",
  // Auto-generates rich metadata
})

Example 3: Detailed NFT Request

User: "Create an NFT of a cyberpunk dragon with these traits: Element=Fire, Rarity=Mythic, Power=9000"

Assistant: "I'll create that NFT with all specified traits:"

• Finds appropriate dragon image from stock photos

• Uploads to IPFS via Pinata

• Creates metadata with all traits

• Mints on XRP Ledger

• Returns IPFS links and transaction hash

Image Sources

1. Stock Photo APIs (current):

   • Unsplash: Free, high-quality photos

   • Pexels: Free stock photos

   • Pixabay: Free images and illustrations

2. User-Provided URLs:

   • Any public image URL

   • Cloud storage links (Dropbox, Google Drive public links)

   • IPFS URLs (already decentralized)

3. Future Enhancements:

   • AI image generation (DALL-E, Stable Diffusion)

   • Direct file uploads

   • Image search integration

Tool Documentation

xrp_get_account_info

Query account details and balances on testnet.

Parameters:

• address (string): XRP Ledger address

Example:

{
  "address": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH"
}

xrp_send_payment

Send XRP or tokens on testnet.

Parameters:

• destination (string): Recipient address

• amount (string): Amount to send

• currency (string, optional): Currency code (default: XRP)

Example:

{
  "destination": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
  "amount": "10",
  "currency": "XRP"
}

xrp_place_order

Create buy/sell orders on the testnet DEX.

Parameters:

• side (string): "buy" or "sell"

• amount (string): Order amount

• price (string): Order price

• pair (string): Trading pair

Example:

{
  "side": "buy",
  "amount": "100",
  "price": "0.5",
  "pair": "USD/XRP"
}

For complete tool documentation with parameters and examples, use the MCP Inspector or refer to the source code.

XRP Ledger Testnet Advantages

• Native DEX Testing: Test the world's oldest DEX operating since 2012

• Native AMM: Test protocol-level automated market makers

• Built-in Escrow: Test time-based and conditional escrow without smart contracts

• Payment Channels: Test micropayment infrastructure for high-frequency transactions

• Fast Settlement: 3-5 seconds for rapid development iteration

• Low Fees: Fraction of a cent per transaction (even lower on testnet)

• Energy Efficient: Minimal environmental impact for extensive testing

• Multi-signing: Test native multi-signature support

Testnet Native Features

Unlike Ethereum-based chains that require smart contracts, XRPL testnet provides:

• Built-in DEX with auto-bridging for comprehensive testing

• Native AMM functionality without external protocols

• Escrow system without contract deployment

• Payment channels for micropayment testing

• Multi-signature transactions for security testing

• Token issuance and management with native commands

Testnet Security & Development

⚠️ TESTNET WARNINGS:

• No Real Value: Testnet tokens have no monetary value

• Network Resets: Testnet may be reset, wiping all data

• Experimental Features: Latest features may be unstable

• Rate Limits: Testnet servers may have stricter rate limits

Development Best Practices

• Test All Features: Thoroughly test DEX, AMM, and escrow functionality

• Account Management: Test both funded and unfunded account scenarios

• Transaction Fees: Monitor fee escalation during network stress

• Sequence Numbers: Test transaction ordering and ticket usage

• Trust Lines: Test token issuance and trust relationships

Development

# Development mode
npm run dev

# Build TypeScript
npm run build

# Run tests
npm test

Technical Details

• Language: TypeScript

• Framework: xrpl.js v4.4.0

• Architecture: MCP Server Protocol

• Networks: Testnet/Devnet support

• Performance: 1,500 TPS, 3-5 second settlement

• Consensus: Unique consensus algorithm (not PoW or PoS)

• Environment: Testnet/Development only

🔒 Security & Best Practices

⚠️ Critical Security Notes

• Testnet Only: This server is configured for XRP Ledger testnet only

• No Private Key Storage: Server never stores private keys or seeds

• Development Tools: Wallet creation tools are for development/testing only

• Network Verification: Always verify network before transactions

🛡️ Security Features

• Input Validation: All inputs validated with Zod schemas

• Error Sanitization: Error messages don't expose sensitive data

• Rate Limiting: Built-in rate limiting protection

• Multi-network Isolation: Testnet/devnet/mainnet environment separation

• Security Testing: Comprehensive injection and XSS protection

• Chaos Testing: Fault tolerance and failure recovery testing

• Private Key Protection: No private key storage or logging

📋 Best Practices

1. Test First: Always test transactions on testnet

2. Verify Addresses: Double-check recipient addresses

3. Fee Management: Monitor transaction fees and reserves

4. Backup Recovery: Keep wallet seeds secure

5. Network Selection: Use appropriate network for your use case

🚨 Security Warnings

• Private Key Exposure: Never share or log private keys or seeds

• Faucet Limits: Testnet faucets have rate limits

• Transaction Confirmation: Wait for ledger validation before considering transactions final

• Trust Line Risks: Verify issuer addresses before creating trust lines

🔧 Troubleshooting

Common Issues

Connection Problems

Problem: "Failed to connect to XRP Ledger" Solution:

• Verify WebSocket URL in environment variables

• Check network connectivity

• Try alternative XRP Ledger nodes

• Ensure testnet node is accessible

Tool Not Found

Problem: "Unknown tool: xrp_tool_name" Solution:

• Verify tool name spelling

• Check MBSS naming convention

• Use xrp_help for tool discovery

• Update MCP server configuration

Balance Returns Zero

Problem: "Balance shows 0 for valid address" Solution:

• Verify address format and network

• Check if address is activated (20 XRP reserve)

• Use testnet faucet if needed

• Wait for ledger synchronization

Account Not Found

Problem: "Account not found error" Solution:

• Account may not be activated

• Fund account with at least 20 XRP

• Use xrp_request_faucet for testnet XRP

• Verify address format

Error Messages

• Invalid address format: Check address format and network

• Account not activated: Fund account with minimum reserve (20 XRP)

• Insufficient XRP balance: Add funds to wallet or use faucet

• Trust line not found: Create trust line before token operations

• Fee exceeds available balance: Ensure sufficient XRP for transaction fees

Getting Help

1. Use xrp_help for interactive assistance

2. Use xrp_search_tools to find relevant tools

3. Check this README for examples

4. Review error logs in server output

🏗️ Technical Architecture

System Components

• Language: TypeScript with strict type checking

• Framework: Model Context Protocol (MCP) SDK

• Validation: Zod schema validation for all inputs

• Testing: Jest with 95%+ coverage, security & chaos tests

• Build System: TypeScript compiler with ES2022 target

• Architecture: MBSS v3.0 compliant modular design

Dependencies

{
  "@modelcontextprotocol/sdk": "^1.0.0",
  "zod": "^3.22.0",
  "xrpl": "^4.4.0",
  "axios": "^1.7.0",
  "uuid": "^10.0.0"
}

File Structure

src/
├── index.ts              # Main server entry point
├── client.ts             # XRP Ledger client abstraction
├── constants.ts          # Configuration constants
├── logger.ts             # MBSS-compliant logging
├── types.ts              # TypeScript type definitions
├── tools/                # Organized tool modules
│   ├── core/             # MBSS v3.0 mandatory tools (25)
│   ├── wallet/           # Wallet management tools
│   ├── tokens/           # Token operations
│   ├── nft/              # NFT operations
│   ├── escrow/           # Escrow operations
│   ├── dex/              # DEX trading tools
│   ├── amm/              # AMM operations
│   ├── advanced/         # Advanced features
│   ├── special/          # AI utilities
│   └── help/             # Help system tools
└── utils/                # Shared utilities

Performance Characteristics

• Response Time: <5 seconds for standard operations

• Concurrent Requests: Up to 10 simultaneous requests

• Memory Usage: ~50MB base + ~10MB per active connection

• Network: Optimized WebSocket connections with reconnection

• Test Coverage: 95%+ enforced with comprehensive testing

• Security: Input validation, injection protection, chaos testing

• Ledger Settlement: 3-5 seconds for transaction validation

• Consensus: Unique RPCA algorithm (not PoW or PoS)

License

MIT