xrpl mcp

# XRP Ledger Model Context Protocol Server [](https://glama.ai/mcp/servers/%40RomThpt/mcp-xrpl) 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](#-overview) - [Features](#-features) - [Supported Networks](#-supported-networks) - [Prerequisites](#️-prerequisites) - [Installation](#-installation) - [Server Configuration](#️-server-configuration) - [Usage](#-usage) - [API Reference](#-api-reference) - [Security Considerations](#-security-considerations) - [Project Structure](#-project-structure) - [Development](#️-development) - [License](#-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 ```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: ``` # 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 ``` 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`](https://www.npmjs.com/package/@modelcontextprotocol/sdk): MCP SDK - [`xrpl`](https://www.npmjs.com/package/xrpl): XRP Ledger JavaScript/TypeScript API - [`dotenv`](https://www.npmjs.com/package/dotenv): Environment variable management - [`zod`](https://www.npmjs.com/package/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.