npm install 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.
- Overview
- Features
- Supported Networks
- Prerequisites
- Installation
- Server Configuration
- Usage
- API Reference
- Security Considerations
- Project Structure
- Development
- License
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.
- Connect to XRPL networks (MainNet, TestNet, DevNet)
- Account information retrieval
- Account property management
- Deposit preauthorization
- Regular key management
- Transfer XRP between accounts
- Get token metadata (name, symbol, decimals, supply)
- Check token balances
- Transfer tokens between addresses
- Approve token spending
- Token clawback
- Mint NFTs on the XRP Ledger
- View NFT metadata
- Verify NFT ownership
- Transfer NFTs between addresses
- Get NFT collections
- Create DIDs on the XRPL
- Resolve DIDs
- Update DID documents
- Deactivate DIDs
- Create Automated Market Makers
- Deposit to AMMs
- Place bids on AMMs
- Vote on AMM parameters
- Delete AMMs
- Clawback assets from AMMs
- Create checks
- Cash checks
- Cancel checks
- Create offers
- Cancel offers
- Set oracle data
- Delete oracle data
- Create payment channels
- Fund payment channels
- Claim from payment channels
- Create escrows
- Finish escrows
- Cancel escrows
- Set and manage trustlines
- Create tickets for transaction processing
- MainNet: Production XRP Ledger network
- TestNet: Test network for development
- DevNet: Development network for experimental features
- Node.js 18.0.0 or higher
``bashClone the repository
git clone https://github.com/yourusername/mcp-xrpl.git
cd mcp-xrpl
āļø 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 removeNetwork selection (default is "testnet")
XRPL_NETWORK=testnet # Options: mainnet, testnet, devnet
`š Usage
$3
`bash
Start the server in stdio mode (for CLI tools)
npm start
`$3
Connect to this MCP server using any MCP-compatible client. For testing and debugging, you can use the MCP Inspector.
š API Reference
$3
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 |$3
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
$3
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$3
@modelcontextprotocol/sdk: MCP SDK
- xrpl: XRP Ledger JavaScript/TypeScript API
- dotenv: Environment variable management
- zod`: TypeScript-first schema declaration and validationThis project is licensed under the terms of the MIT License.
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.