# XRPL MCP Server

A Model Context Protocol (MCP) server that provides read-only access to the XRP Ledger. Query accounts, transactions, NFTs, DEX order books, and more.

## Features

- **Account Operations**: Get account info, balances, trust lines, transaction history
- **Transaction Lookup**: Retrieve detailed transaction information by hash
- **Ledger Data**: Query ledger state and server information
- **NFT Support**: List account NFTs and get NFT details
- **DEX Integration**: View account offers and order books
- **Multi-Network**: Supports Mainnet, Testnet, and Devnet

## Installation

```bash
git clone https://github.com/esonica/mcp_xrpl.git
cd mcp_xrpl
npm install
npm run build
```

## Configuration

### Claude Desktop

Add to your Claude Desktop configuration file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "xrpl": {
      "command": "node",
      "args": ["C:/path/to/mcp_xrpl/build/index.js"]
    }
  }
}
```

### Claude Code

Add to your Claude Code MCP settings (`.claude/settings.json`):

```json
{
  "mcpServers": {
    "xrpl": {
      "command": "node",
      "args": ["C:/path/to/mcp_xrpl/build/index.js"]
    }
  }
}
```

## Network Selection

All tools accept an optional `network` parameter:

| Network | Description | WebSocket URL |
|---------|-------------|---------------|
| `mainnet` | Production XRP Ledger (default) | wss://xrplcluster.com |
| `testnet` | Test network with test XRP | wss://s.altnet.rippletest.net:51233 |
| `devnet` | Development network | wss://s.devnet.rippletest.net:51233 |

---

## Tools Reference

### Account Tools

#### `get_account_info`

Get detailed information about an XRPL account including balance, sequence number, and flags.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `account` | string | Yes | The XRPL account address (starts with r) |
| `network` | string | No | Network to query: `mainnet`, `testnet`, or `devnet` |

**Example:**
```json
{
  "account": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
  "network": "mainnet"
}
```

**Returns:** Account balance (in drops), sequence number, flags, owner count, and other account settings.

---

#### `get_account_lines`

Get trust lines (token balances) for an XRPL account. Shows all issued currencies the account holds.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `account` | string | Yes | The XRPL account address (starts with r) |
| `peer` | string | No | Filter to trust lines with this specific issuer |
| `limit` | number | No | Maximum number of trust lines to return (default: 200) |
| `network` | string | No | Network to query: `mainnet`, `testnet`, or `devnet` |

**Example:**
```json
{
  "account": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
  "limit": 50
}
```

**Returns:** Array of trust lines with currency code, balance, limit, and issuer for each.

---

#### `get_account_currencies`

Get a list of currencies an account can send or receive.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `account` | string | Yes | The XRPL account address (starts with r) |
| `network` | string | No | Network to query: `mainnet`, `testnet`, or `devnet` |

**Example:**
```json
{
  "account": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"
}
```

**Returns:** Lists of `send_currencies` and `receive_currencies`.

---

#### `get_account_transactions`

Get transaction history for an XRPL account.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `account` | string | Yes | The XRPL account address (starts with r) |
| `limit` | number | No | Maximum transactions to return (default: 20) |
| `forward` | boolean | No | If true, return oldest first (default: false, newest first) |
| `network` | string | No | Network to query: `mainnet`, `testnet`, or `devnet` |

**Example:**
```json
{
  "account": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
  "limit": 10,
  "forward": false
}
```

**Returns:** Array of transactions with full transaction details and metadata.

---

### Transaction Tools

#### `get_transaction`

Get detailed information about a specific transaction by its hash.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `transaction_hash` | string | Yes | The transaction hash (64 character hex string) |
| `binary` | boolean | No | If true, return as binary blob (default: false) |
| `network` | string | No | Network to query: `mainnet`, `testnet`, or `devnet` |

**Example:**
```json
{
  "transaction_hash": "E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BCCABD0B9C4226"
}
```

**Returns:** Full transaction details including type, accounts involved, amounts, and result.

---

### Ledger Tools

#### `get_ledger`

Get information about a specific ledger or the latest validated ledger.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ledger_index` | string | No | Ledger index or `validated`, `closed`, `current` (default: validated) |
| `transactions` | boolean | No | Include transaction hashes (default: false) |
| `expand` | boolean | No | Include full transaction details (default: false) |
| `network` | string | No | Network to query: `mainnet`, `testnet`, or `devnet` |

**Example:**
```json
{
  "ledger_index": "validated",
  "transactions": true
}
```

**Returns:** Ledger header info including hash, close time, transaction count, and state hash.

---

#### `get_server_info`

Get information about the XRPL server/node including its current state and sync status.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network` | string | No | Network to query: `mainnet`, `testnet`, or `devnet` |

**Example:**
```json
{
  "network": "testnet"
}
```

**Returns:** Server version, uptime, validated ledger range, peer count, and sync state.

---

#### `ping`

Ping the XRPL server to check connectivity and measure response time.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network` | string | No | Network to ping: `mainnet`, `testnet`, or `devnet` |

**Example:**
```json
{
  "network": "mainnet"
}
```

**Returns:** Connection status, response time in milliseconds, and network info.

---

### NFT Tools

#### `get_account_nfts`

Get all NFTs (Non-Fungible Tokens) owned by an XRPL account.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `account` | string | Yes | The XRPL account address (starts with r) |
| `limit` | number | No | Maximum NFTs to return (default: 100) |
| `network` | string | No | Network to query: `mainnet`, `testnet`, or `devnet` |

**Example:**
```json
{
  "account": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
  "limit": 50
}
```

**Returns:** Array of NFTs with NFT ID, issuer, serial number, URI, and flags.

---

#### `get_nft_info`

Get detailed information about a specific NFT by its NFT ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `nft_id` | string | Yes | The NFT ID (64 character hex string) |
| `network` | string | No | Network to query: `mainnet`, `testnet`, or `devnet` |

**Example:**
```json
{
  "nft_id": "00081388DC1AB4937C899037B2FDFC3CB20F6F64E73120BB5F8AA66A00000228"
}
```

**Returns:** NFT details including owner, issuer, taxon, serial, URI, and flags.

---

### DEX Tools

#### `get_account_offers`

Get all open DEX (Decentralized Exchange) offers for an XRPL account.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `account` | string | Yes | The XRPL account address (starts with r) |
| `limit` | number | No | Maximum offers to return (default: 200) |
| `network` | string | No | Network to query: `mainnet`, `testnet`, or `devnet` |

**Example:**
```json
{
  "account": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"
}
```

**Returns:** Array of open offers with taker_gets, taker_pays, sequence, and quality.

---

#### `get_order_book`

Get the order book for a currency pair on the XRPL DEX.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `base_currency` | string | Yes | Base currency code (e.g., "XRP", "USD") |
| `base_issuer` | string | No | Issuer for base currency (not needed for XRP) |
| `quote_currency` | string | Yes | Quote currency code (e.g., "XRP", "USD") |
| `quote_issuer` | string | No | Issuer for quote currency (not needed for XRP) |
| `limit` | number | No | Maximum offers per side (default: 20) |
| `network` | string | No | Network to query: `mainnet`, `testnet`, or `devnet` |

**Example - XRP/USD order book:**
```json
{
  "base_currency": "XRP",
  "quote_currency": "USD",
  "quote_issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
  "limit": 10
}
```

**Example - USD/EUR order book:**
```json
{
  "base_currency": "USD",
  "base_issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
  "quote_currency": "EUR",
  "quote_issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq"
}
```

**Returns:** Object with `asks` and `bids` arrays containing order book offers.

---

## Common Issuers

Here are some well-known token issuers on XRPL mainnet:

| Issuer | Address | Tokens |
|--------|---------|--------|
| Bitstamp | `rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B` | USD, BTC, EUR |
| GateHub | `rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq` | USD, EUR, GBP |

---

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode (rebuild on changes)
npm run dev
```

## License

MIT