XRPL MCP Server

MCP server for:

• LOS (https://los.prod.ripplex.io)
• Validator History Service (https://data.xrpl.org)
• XRPL JSON-RPC (https://s1.ripple.com:51234)
• XRPLMeta (https://s1.xrplmeta.org)

Setup

npm install
npm start

npm start runs the server over Streamable HTTP at http://127.0.0.1:3000/mcp by default. For stdio mode (used by some local MCP clients and the all-tools harness), run:

npm run start:stdio

Environment Variables

• LOS_BASE_URL (default: https://los.prod.ripplex.io)
• DATA_XRPL_BASE_URL (default: https://data.xrpl.org)
• XRPL_RPC_URL (default: https://s1.ripple.com:51234)
• XRPLMETA_BASE_URL (default: https://s1.xrplmeta.org)
• MCP_TRANSPORT (default: http, options: http or stdio)
• MCP_HTTP_HOST (default: 0.0.0.0)
• MCP_HTTP_PORT (default: 3000)
• MCP_HTTP_PATH (default: /mcp)

MCP Client Config (http, default)

{
  "mcpServers": {
    "xrpl-data": {
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:3000/mcp"
      }
    }
  }
}

MCP Client Config (stdio, optional)

{
  "mcpServers": {
    "xrpl-data": {
      "command": "node",
      "args": ["/Users/ashraychowdhry/Documents/xrpl-data-mcp/src/server.js"],
      "env": {
        "LOS_BASE_URL": "https://los.prod.ripplex.io",
        "DATA_XRPL_BASE_URL": "https://data.xrpl.org",
        "XRPL_RPC_URL": "https://s1.ripple.com:51234",
        "XRPLMETA_BASE_URL": "https://s1.xrplmeta.org"
      }
    }
  }
}

Response Formats

1) Low-level passthrough tools

Most low-level tools (los_*, vh_*, xrpl_*, validator_history_get, xrpl_public_api_call) return the upstream JSON payload in MCP text content.

Typical shapes:

• XRPL RPC tools: { "result": { ... }, "status": "success", "warnings"?: [...] }
• VHS/LOS GET tools: service-native object/array response

2) Agent-first composite tools

These return a normalized envelope:

{
  "data": {},
  "sources": [{ "system": "LOS|VHS|rippled|XRPLMeta", "method": "...", "at": "..." }],
  "freshness": { "asOfLedger": 0, "asOfTime": "..." },
  "warnings": []
}

3) Error format

On upstream/API/runtime failure, tools return MCP error content with isError: true and human-readable text (often including upstream HTTP status/body).

How To Use Tools

Call MCP tools with:

• name: tool id
• arguments: JSON object matching the tool input schema below

Example:

{
  "name": "xrpl_account_info",
  "arguments": {
    "account": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
    "ledger_index": "validated"
  }
}

How To Use This Server (Step-by-step)

1. Install dependencies.

   npm install
   

2. Start the server locally.

   npm start
   

3. Add the MCP server config to your MCP client (use the http config above by default).
4. In your MCP client, run tools/list to discover all available tools.
5. Start with a simple connectivity check:
   • xrpl_server_info
   • network_overview
6. For entity-specific lookups, use resolve_entities first, then call suggested tools.
7. For topology-specific calls:
   • call vh_topology_nodes first
   • take a pubkey from that response
   • call vh_topology_node with that pubkey
8. For token/NFT-specific calls, discover live IDs first:
   • token: los_get_trusted_tokens
   • nft: xrpl_nft_info / xrpl_nft_history after discovering an nft_id
9. Run the full validation suite to verify end-to-end health:

   node scripts/test-all-tools.mjs > /tmp/xrpl-mcp-test-results.json
   

10. Manually call a single tool over HTTP:

    node scripts/test-http-tool.mjs http://127.0.0.1:3000/mcp xrpl_server_info '{}'
    

Full Tool Catalog (49)

Agent-first composite tools (12)

Tool	Description	Required arguments	Expected response format
network_overview	Network identity, health summary, LOS freshness	none	Envelope: data includes server/network/health metrics
ledger_summary	Canonical ledger facts + LOS hints	none (ledger_index/ledger_hash optional)	Envelope: data.ledger, ledger metadata, optional LOS artifacts
tx_explain	Normalized transaction explanation/classification	tx_hash	Envelope: tx details, classification, token/entity hints
account_overview	Account state/activity summary	account	Envelope: balances, trustlines, activity histogram, risk indicators
token_overview	Consolidated issued-token view	issuer, currency	Envelope: token metadata, holders/trustlines, liquidity/activity
market_snapshot	Orderbook + AMM + recent LOS trades	base, quote	Envelope: orderbook summary, AMM state, trade sample/VWAP
amm_overview	AMM state and swap activity	none (amm_id or assetA+assetB recommended)	Envelope: AMM state, swap sample, aggregate volume
validator_set_overview	Validator set composition summary	none (options.group optional)	Envelope: validator count, operator concentration, set sample
validator_health	Validator reliability metrics	pubkey_or_node	Envelope: validator profile + signed/missed/uptime-like metrics
amendment_status	Amendment enablement + context	none (network optional)	Envelope: enabled amendments, vote context, network context
search_transactions	Filtered LOS transaction search + aggregates	filters	Envelope: results, cursor, aggregate stats
resolve_entities	Pattern-based XRPL entity resolver	input	Envelope: resolved entity type + suggested next tools

LOS tools (4)

Tool	Description	Required arguments	Expected response format
los_get_token	Fetch one LOS token by tokenID (currencyHex.issuer)	tokenID	LOS token object
los_batch_get_tokens	Batch fetch LOS tokens	tokenIds (array)	LOS batch token response
los_get_trusted_tokens	List trusted/KYC tokens	none	LOS trusted token list (count, tokens)
los_get_transactions	Query LOS transactions with paging/sort	none (token strongly recommended)	LOS transaction query response (results/cursor fields)

Validator history tools (15)

Tool	Description	Required arguments	Expected response format
vh_list_networks	List tracked networks	none	VHS networks payload (result, networks)
vh_topology_nodes	Topology nodes for all/specific network	none (network optional)	VHS topology nodes payload
vh_topology_node	Topology for a specific node pubkey	pubkey	VHS topology node payload
vh_list_validators	List validators (optionally by group)	none (group optional)	VHS validators payload
vh_get_validator	Validator detail	pubkey	VHS validator profile
vh_get_validator_manifests	Validator manifest history	pubkey	VHS manifest history payload
vh_get_validator_reports	Validator reports	pubkey	VHS validator reports payload
vh_get_daily_validator_reports	Daily validator reports collection	none	VHS daily report payload
vh_get_amendments_info	Amendment metadata	none	VHS amendments info payload
vh_get_amendment_info	Amendment info by name/id	amendment	VHS amendment detail payload
vh_get_amendments_vote	Amendment votes for a network	network	VHS amendment votes payload
vh_get_amendment_vote	Single amendment vote status	network, identifier	VHS amendment vote detail payload
vh_health	VHS health summary	none	VHS health payload
vh_metrics	VHS Prometheus metrics	none	Metrics text/structured payload returned as text
validator_history_get	Generic VHS GET passthrough	path	Raw VHS response for requested path

XRPL JSON-RPC tools (17)

Tool	Description	Required arguments	Expected response format
xrpl_account_info	Account root info	account	XRPL RPC result object
xrpl_account_objects	Objects owned by account	account	XRPL RPC result object
xrpl_account_lines	Trust lines	account	XRPL RPC result object
xrpl_account_tx	Account tx history	account	XRPL RPC result object
xrpl_ledger	Ledger by hash/index	none	XRPL RPC result object
xrpl_ledger_data	Raw ledger state pages	none	XRPL RPC result object
xrpl_ledger_entry	Single ledger entry	none (one locator required by XRPL)	XRPL RPC result object
xrpl_tx	Transaction by hash	transaction	XRPL RPC result object
xrpl_book_offers	Orderbook offers	taker_gets, taker_pays	XRPL RPC result object
xrpl_amm_info	AMM pool info	asset, asset2	XRPL RPC result object
xrpl_nft_info	NFToken state/metadata	nft_id	XRPL RPC result object
xrpl_nft_history	NFToken ownership/transfer history	nft_id	XRPL RPC result object
xrpl_nfts_by_issuer	NFTs by issuer	issuer	XRPL RPC result object
xrpl_server_info	Server status/validated range	none	XRPL RPC result object
xrpl_fee	Fee metrics	none	XRPL RPC result object
xrpl_public_api_call	Generic JSON-RPC method call	method	XRPL RPC result object
xrpl_list_recommended_methods	Curated method list exposed by dedicated tools	none	{ "methods": [...] }

XRPLMeta tools (1)

Tool	Description	Required arguments	Expected response format
xrplmeta_get	Generic XRPLMeta GET passthrough	path	Envelope: data contains XRPLMeta response

Input Discovery Notes (for reliable testing)

Some tools need live identifiers. The test harness discovers them first:

• vh_topology_node.pubkey: taken from vh_topology_nodes output
• vh_get_validator* / validator_health: taken from vh_list_validators
• tx_explain / xrpl_tx: tx hash from xrpl_account_tx
• xrpl_nft_info / xrpl_nft_history: NFT id from recent NFT transactions
• los_get_token / token-dependent tools: token from los_get_trusted_tokens

Test Results

Latest end-to-end live run (2026-02-20):

• Tools tested: 49
• Passed: 49
• Failed: 0

Run command:

node scripts/test-all-tools.mjs > /tmp/xrpl-mcp-test-results.json

Detailed output:

• /tmp/xrpl-mcp-test-results.json
• /Users/ashraychowdhry/Documents/xrpl-data-mcp/docs/TEST_RESULTS.md