# XRPL MCP Server

An MCP server that gives AI assistants structured access to XRP Ledger data and network actions.

## Requirements

- Python 3.10 or newer

## Features

- Get account balances and sequence numbers
- Query trust lines and issued currencies
- View NFTs owned by an account
- Retrieve account transaction history
- Fetch individual transaction details
- Inspect DEX order book offers
- Retrieve XRPL server status
- Submit signed transactions

## Package Chooser

Pick the install target that matches how you plan to use the server.

| Package | PyPI | Install | Use when |
| --- | --- | --- | --- |
| Published package | [![PyPI version](https://img.shields.io/pypi/v/iflow-mcp_lgcarrier-xrpl-mcp-server)](https://pypi.org/project/iflow-mcp_lgcarrier-xrpl-mcp-server/) | `python -m pip install iflow-mcp_lgcarrier-xrpl-mcp-server` | Recommended if you want the packaged CLI/server immediately and do not need an editable checkout. |
| Source checkout | — | `python -m pip install -e ".[dev]"` | You are developing in this repo, running tests, or using the local `mcp dev` / `mcp install` workflows below. |

## Quickstart

The quickstart below is the source-checkout path for local development and MCP registration. If you only need the published package, use the PyPI install command above.

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
```

```bash
mcp install src/xrpl_mcp_server/server.py:mcp --with-editable .
```

First prompt to try:

> What is the XRP balance and sequence number for account rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe?

## Installation

### From source

```bash
git clone https://github.com/lgcarrier/xrpl-mcp-server.git
cd xrpl-mcp-server
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
```

This installs the package in editable mode and includes the `mcp` CLI used for local development and Claude Desktop integration.

### From PyPI

The published package name is different from the GitHub repository name.

```bash
python -m pip install iflow-mcp_lgcarrier-xrpl-mcp-server
```

## Configuration

The server uses the following environment variable:

- `XRPL_NODE_URL`: XRP Ledger JSON-RPC endpoint.
  Default: `https://s1.ripple.com:51234/`

## Safety Note

By default, the server connects to Ripple's public mainnet endpoint. That means:

- read-only tools query live mainnet data
- `submit_transaction` submits a signed transaction to the live XRP Ledger network

Only use `submit_transaction` when you intend to broadcast a real signed transaction.

For testing, point the server to testnet before launching it:

```bash
export XRPL_NODE_URL="https://s.altnet.rippletest.net:51234/"
python -m xrpl_mcp_server
```

You can also install the Claude Desktop entry with the environment variable set:

```bash
mcp install src/xrpl_mcp_server/server.py:mcp --with-editable . \
  --env-var XRPL_NODE_URL=https://s.altnet.rippletest.net:51234/
```

## Usage

### Run directly from source

```bash
python -m xrpl_mcp_server
```

### Run as an installed package

```bash
xrpl-mcp-server
```

### Inspect locally with the MCP Inspector

```bash
mcp dev src/xrpl_mcp_server/server.py:mcp --with-editable .
```

### Install into Claude Desktop

```bash
mcp install src/xrpl_mcp_server/server.py:mcp --with-editable .
```

If you prefer `uv`, the equivalent commands are `uv run mcp dev ...` and `uv run mcp install ...`.

## Available Tools

All tools keep their existing names and arguments. Successful calls return structured MCP outputs instead of plain text or JSON-encoded strings.

### `get_account_info`

Parameters:

- `address` (`string`): XRP Ledger account address

Returns a structured object with:

- `account`
- `balance_drops`
- `balance_xrp`
- `sequence`

### `get_account_lines`

Parameters:

- `address` (`string`): XRP Ledger account address
- `peer` (`string`, optional): Counterparty account filter
- `limit` (`integer`, optional): Maximum number of trust lines

Returns the XRPL `account_lines` result object.

### `get_account_nfts`

Parameters:

- `address` (`string`): XRP Ledger account address
- `limit` (`integer`, optional): Maximum number of NFTs

Returns the XRPL `account_nfts` result object.

### `get_account_transactions`

Parameters:

- `address` (`string`): XRP Ledger account address
- `limit` (`integer`, optional): Maximum number of transactions
- `binary` (`boolean`, optional): Return transactions in binary form
- `forward` (`boolean`, optional): Search forward through ledger history

Returns the XRPL `account_tx` result object.

### `get_server_info`

Returns the XRPL `server_info` result object.

### `submit_transaction`

Parameters:

- `tx_blob` (`string`): Signed transaction blob in hex format

Returns the XRPL `submit` result object.

### `get_transaction_info`

Parameters:

- `transaction_hash` (`string`): Transaction hash

Returns the XRPL `tx` result object.

### `get_book_offers`

Parameters:

- `taker_gets` (`object`): Currency/issuer object the taker wants to receive
- `taker_pays` (`object`): Currency/issuer object the taker wants to pay
- `limit` (`integer`, optional): Maximum number of offers

Returns the XRPL `book_offers` result object.

## Errors

Tool failures are returned as MCP tool errors rather than success payloads. Common cases include:

- account lookups for missing addresses, such as `actNotFound`
- transaction lookups for unknown hashes, such as `txnNotFound`
- upstream XRPL request failures, including submission errors and transport exceptions

Example not-found error:

```text
Account rMissingExampleAddress not found on the ledger.
```

Example submission error:

```text
Submitting transaction failed: tefFAILURE: submission rejected
```

## Examples

### `get_account_info`

Prompt:

> What is the balance of the XRP account rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe?

Structured result:

```json
{
  "account": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
  "balance_drops": "25500000",
  "balance_xrp": "25.5",
  "sequence": 123456
}
```

### `get_account_transactions`

Prompt:

> Show me the two most recent transactions for rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe.

Representative result shape:

```json
{
  "account": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
  "ledger_index_max": 98765432,
  "ledger_index_min": 98765400,
  "transactions": [
    {
      "tx": {
        "hash": "ABC123...",
        "TransactionType": "Payment"
      },
      "validated": true
    },
    {
      "tx": {
        "hash": "DEF456...",
        "TransactionType": "TrustSet"
      },
      "validated": true
    }
  ]
}
```

### `get_book_offers`

Prompt:

> Show me the first three book offers for XRP/USD on the XRPL DEX.

Representative result shape:

```json
{
  "ledger_current_index": 98765432,
  "offers": [
    {
      "Account": "rOfferMaker1",
      "Sequence": 100,
      "quality": "0.5"
    },
    {
      "Account": "rOfferMaker2",
      "Sequence": 101,
      "quality": "0.51"
    }
  ]
}
```

## Development

Run the test suite:

```bash
pytest
```

## License

MIT License