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.

🏗️ 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

Check balance:

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

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

Get a Pinata Account (Recommended)
- Sign up at pinata.cloud
- Get 1GB free storage (50% off with code NFTSTORAGE50)
- Create API keys in dashboard

Configure Environment

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

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

Stock Photo APIs (current):
- Unsplash: Free, high-quality photos
- Pexels: Free stock photos
- Pixabay: Free images and illustrations
User-Provided URLs:
- Any public image URL
- Cloud storage links (Dropbox, Google Drive public links)
- IPFS URLs (already decentralized)
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

Test First: Always test transactions on testnet
Verify Addresses: Double-check recipient addresses
Fee Management: Monitor transaction fees and reserves
Backup Recovery: Keep wallet seeds secure
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

Use xrp_help for interactive assistance
Use xrp_search_tools to find relevant tools
Check this README for examples
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

XRP Ledger Testnet MCP Server

🎯 Quick Overview

🏗️ Server Architecture

✨ Key Features

🔗 Core XRP Ledger Operations

💼 Wallet Management

🪙 Payment & DEX Operations

AMM Operations (1 tool)

Token/Currency Operations (4 tools)

Escrow Operations (4 tools)

NFT Operations (6 tools)

AI & Assistant Utilities (2 tools)

Network & Ledger Operations (7 tools)

Implementation Status

🚀 Installation

Prerequisites

Quick Start

Configuration

MCP Integration

Docker Support

📖 Usage Examples

Basic Operations

Get Network Information

Check Balance

Create Wallet (Development Only)

Advanced Workflows

Complete Transaction Flow

AI Integration Examples

Claude Desktop Integration

Tool Discovery

🛠️ Complete Tool Reference

MBSS v3.0 Core Tools (25 Mandatory)

1. xrp_get_chain_info

2. xrp_get_balance

3. xrp_get_transaction

XRP-Specific Tools (29 Additional)

NFT Operations (6 tools)

Token/Currency Operations (4 tools)

Escrow Operations (4 tools)

DEX & AMM Operations (5 tools)

Network & Ledger Operations (7 tools)

AI & Assistant Utilities (2 tools)

Account & Wallet Management (1 additional)

🌐 Supported Networks

Primary Network

Additional Networks

Testnet Faucets

RPC Endpoints

Environment Variables

Testnet Resources

IPFS Integration for NFTs 🆕

Setting up IPFS Storage

IPFS Benefits

Conversational Usage Examples

Example 1: Quick NFT with Stock Image

Example 2: NFT with Your Own Image

Example 3: Detailed NFT Request

Image Sources

Tool Documentation

xrp_get_account_info

xrp_send_payment

xrp_place_order

XRP Ledger Testnet Advantages

Testnet Native Features

Testnet Security & Development

Development Best Practices

Development

Technical Details

🔒 Security & Best Practices

⚠️ Critical Security Notes

🛡️ Security Features

📋 Best Practices

🚨 Security Warnings

🔧 Troubleshooting

Common Issues

Connection Problems

Tool Not Found

Balance Returns Zero

Account Not Found

Error Messages

1. `xrp_get_chain_info`

2. `xrp_get_balance`

3. `xrp_get_transaction`