🔒 Monero MCP Server

The world's first MCP server for Monero. Give any AI agent a private wallet.

---

What is this?

This is a bridge between AI agents and the Monero network. It lets any AI agent – OpenClaw, Agent Zero, Claude, or any MCP-compatible framework – check balances, receive payments, and send XMR through a simple tool interface.

Think of it as: your AI agent gets its own Monero wallet.

Wait, what's MCP?

MCP (Model Context Protocol) is a standard created by Anthropic that lets AI assistants use external tools. Instead of the AI just generating text, it can call real functions – read files, query databases, or in this case, interact with a Monero wallet.

If you've ever wanted your AI agent to autonomously receive and send XMR – whether it's an OpenClaw agent running a service, an Agent Zero instance managing its own budget, or just Claude checking your balance – that's what this does.

Why Monero? Why not Ethereum or Bitcoin?

Because AI agents need privacy more than humans do.

When a human makes transactions, there's natural noise – you buy coffee at random times, pay rent irregularly, your patterns are chaotic. An AI agent is different. Every transaction follows logic. On a transparent blockchain, anyone can watch an agent's on-chain behavior and reverse-engineer its strategy, its triggers, and how to exploit it.

Monero's privacy-by-default design means an agent's transaction history, balance, and counterparties are hidden. That's not a nice-to-have – it's a security requirement for any autonomous agent handling real value.

Privacy is not a feature for AI agents. It's infrastructure.

Features

12 tools covering everything an AI agent needs:

Category	Tools
Balance & Info	get_balance, get_address, get_height, get_version
Transactions	get_transfers, get_transfer_by_txid
Receiving	create_address, make_integrated_address
Sending	transfer, sweep_all, confirm_transfer
Validation	validate_address
Optional (opt-in)	get_exchange_rate (XMR/USD, XMR/EUR; set MONERO_ENABLE_PRICE_FEED=true)

Read-only by default. Sending XMR requires explicit opt-in via environment variable.

Security: Built for a hostile world

This server assumes the AI agent will encounter prompt injection attacks – malicious text designed to trick the AI into sending funds to an attacker. The AI is not our security boundary. The MCP server is.

Five defense layers, all configurable:

🛡️ Address Allowlist – Lock transfers to known addresses only. Prompt injection can't send to unknown wallets.

🛡️ Two-Step Confirmation – Transfers return a preview + one-time token. Must call confirm_transfer to execute. Attackers can't predict the token.

🛡️ Rate Limiting – Cooldown between transfers + daily XMR limit. Limits damage even if everything else fails.

🛡️ Audit Log – Every tool call logged as JSONL. Rejected transfers are logged too – those are the interesting ones.

🛡️ Input Sanitization – Strict base58 validation before anything reaches the RPC.

This is a tool that can move real money. We built the security for that reality.

Quickstart (5 min)

Get a mainnet receive address and verify the MCP server without downloading the blockchain:

git clone <this-repo> && cd monero-mcp
npm install && npm run build
docker compose up -d
./test-connection.sh

You’ll see your mainnet receive address. Send XMR to it. To test the MCP handshake (stdio):

node test-mcp-stdio.mjs

Optional: run the full MCP test script (build + stdio test; runs npm install if needed):

./test-mcp.sh

Claude Desktop Integration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "monero": {
      "command": "npx",
      "args": ["-y", "monero-mcp@latest"],
      "env": {
        "MONERO_RPC_HOST": "127.0.0.1",
        "MONERO_RPC_PORT": "18082",
        "MONERO_NETWORK": "mainnet",
        "MONERO_ALLOW_TRANSFERS": "false"
      }
    }
  }
}

Restart Claude Desktop. Ask: "What's my Monero balance?" to verify.

Cursor / Claude Code Integration

Add to .cursor/mcp.json or Claude Code MCP config:

{
  "mcpServers": {
    "monero": {
      "command": "npx",
      "args": ["-y", "monero-mcp@latest"],
      "env": {
        "MONERO_RPC_HOST": "127.0.0.1",
        "MONERO_RPC_PORT": "18082",
        "MONERO_NETWORK": "stagenet",
        "MONERO_ALLOW_TRANSFERS": "false"
      }
    }
  }
}

Docker

docker run -e MONERO_RPC_HOST=host.docker.internal \
           -e MONERO_RPC_PORT=18082 \
           -e MONERO_NETWORK=stagenet \
           ghcr.io/baltsar/monero-mcp:latest

---

Agent Zero integration

To use this MCP server with Agent Zero in Docker:

1. See AGENT-ZERO-DOCKER-SETUP.md for the container run command and volume mount.
2. Wallet persistence: If containers are recreated, the wallet can be lost unless it runs on the host or uses a persistent volume. For the most robust setup, run monero-wallet-rpc on the host and point MCP at host.docker.internal:18083. Details and backup steps: AGENT-ZERO-DOCKER-SETUP.md#wallet-persistence-critical.
3. Verification (Agent Zero + Docker): Before relying on your wallet: (1) Confirm wallet-rpc is not running inside the Agent Zero container. (2) Confirm wallet files exist on the host (e.g. ~/monero-wallet/) or that you use this repo’s docker compose (wallet lives in the wallet-data volume). Full checklist: AGENT-ZERO-DOCKER-SETUP.md → Verification.
4. In Agent Zero → Settings → MCP, add a server:

Field	Value
Name	monero
Command	node
Args	/monero-mcp/build/index.js

Env: MONERO_RPC_HOST=host.docker.internal, MONERO_RPC_PORT=18083, MONERO_NETWORK=mainnet, MONERO_ALLOW_TRANSFERS=false (read-only).

Copy-paste config and troubleshooting: AGENT-ZERO-DOCKER-SETUP.md.

---

Remote nodes

The default stack uses a remote node (no local blockchain sync). Default daemon in docker-compose.yml:

• Default: rucknium.me:18081

If you get "no connection to daemon", change --daemon-address in docker-compose.yml to one of these and recreate wallet-rpc:

• xmr-node.cakewallet.com:18081
• node.moneroworld.com:18089

To run your own node and download the chain: docker compose --profile local-node up -d.

---

Troubleshooting

Problem	What to do
"no connection to daemon"	Switch remote node in docker-compose.yml (see Remote nodes above) and run docker compose up -d --force-recreate wallet-rpc.
Wallet disappeared after container recreated	Run wallet-rpc on the host, or use a persistent volume for the wallet dir and never run docker compose down -v. See AGENT-ZERO-DOCKER-SETUP.md → Wallet persistence.
Empty address in test-connection.sh	Install jq for reliable JSON parsing, or use the script’s built-in grep fallback (ensure wallet-rpc is up and has an open wallet).
wallet-rpc won’t start	Check that entrypoint-wallet.sh does not add --rpc-bind-ip (compose already passes it). You must have --confirm-external-bind in the entrypoint for binding to 0.0.0.0.
test-mcp.sh: "tsc: command not found"	Run npm install in the repo first; the script will also run it automatically if node_modules is missing.

---

Manual setup (no Docker)

Prerequisites

You need a running monero-wallet-rpc instance. If you're just testing:

# Download Monero CLI from https://getmonero.org/downloads
# Start the daemon on stagenet (test network, no real money)
monerod --stagenet --detach

# Start wallet RPC on stagenet
monero-wallet-rpc --stagenet \
  --rpc-bind-port 38082 \
  --wallet-dir ./wallets \
  --disable-rpc-login

Install & Build

# From this repo root:
npm install
npm run build

Configure

Copy .env.example and edit:

cp .env.example .env

MONERO_RPC_HOST=127.0.0.1
MONERO_RPC_PORT=38082
MONERO_NETWORK=stagenet

# Safety defaults – read only
MONERO_ALLOW_TRANSFERS=false
MONERO_REQUIRE_CONFIRMATION=true
MONERO_TRANSFER_COOLDOWN_SECONDS=60
MONERO_AUDIT_LOG_FILE=./monero-mcp-audit.jsonl

Connect to your agent

This is a standard MCP server using stdio transport. Connect it to any MCP-compatible agent or framework.

Example – start the server manually:

node build/index.js

The server communicates over stdin/stdout using JSON-RPC (MCP protocol). Point your agent framework's MCP client config at the binary and you're good.

Works with OpenClaw, Agent Zero, Claude Code, Cursor, any local LLM setup with MCP support – whatever you run.

Test with MCP Inspector

npx @modelcontextprotocol/inspector

MCP Docs

• Protocol: Model Context Protocol
• TypeScript SDK: modelcontextprotocol/typescript-sdk

Configuration Reference

Variable	Default	Description
MONERO_RPC_HOST	127.0.0.1	Wallet RPC host
MONERO_RPC_PORT	18082	Wallet RPC port
MONERO_RPC_USER	–	RPC username (digest auth)
MONERO_RPC_PASS	–	RPC password (digest auth)
MONERO_NETWORK	mainnet	mainnet, stagenet, or testnet
MONERO_ALLOW_TRANSFERS	false	Enable send operations
MONERO_MAX_TRANSFER_AMOUNT	–	Max XMR per single transfer
MONERO_DAILY_LIMIT_XMR	–	Max XMR sent per rolling 24h
MONERO_TRANSFER_COOLDOWN_SECONDS	0	Min seconds between transfers
MONERO_ALLOWED_ADDRESSES	–	Comma-separated address allowlist
MONERO_REQUIRE_CONFIRMATION	true	Two-step transfer confirmation
MONERO_AUDIT_LOG_FILE	–	Path for JSONL audit log
MONERO_ENABLE_PRICE_FEED	false	Enable get_exchange_rate (external API; see privacy note in .env.example)

Recommended Production Config

MONERO_ALLOW_TRANSFERS=true
MONERO_ALLOWED_ADDRESSES=4YourTrustedAddress1,4YourTrustedAddress2
MONERO_REQUIRE_CONFIRMATION=true
MONERO_DAILY_LIMIT_XMR=1.0
MONERO_TRANSFER_COOLDOWN_SECONDS=300
MONERO_AUDIT_LOG_FILE=./audit.jsonl

Networks

Network	Daemon Port	Wallet RPC Port	Address Prefix	Real Money?
Mainnet	18081	18082	4 / 8	✅ Yes
Stagenet	38081	38082	5 / 7	❌ No – use this for testing
Testnet	28081	28082	9 / B	❌ No

⚠️ Status: Early Alpha

This is v0.1 – built in a night before heading to Monerotopia.

It compiles, the security layers are in place, but it has NOT been audited. Do not use with mainnet funds you can't afford to lose.

If you're a Monero developer or security researcher: tear it apart. That's how we make it production-ready.

⚠️ Important Warnings

This software is not audited. It is early-stage, open-source software that interacts with real money. Use at your own risk.

Your seed phrase is your responsibility. Write it down. Store it offline. If you lose it, your funds are gone permanently. No one can help you.

AI agents can be manipulated. The security layers in this server (address allowlists, two-step confirmation, rate limiting, audit logging) reduce risk but do not eliminate it. Always use all available protections in production.

Do not use with funds you cannot afford to lose.

Start on stagenet. Test everything there before going near mainnet. Free test XMR is available via faucets.

See DISCLAIMER.md for full details.

Contributing

We need help. This is v0.1 and there's a lot to do. See CONTRIBUTING.md for details.

Good first issues:

• Better error messages for common RPC failures
• Transaction memo/note support
• Multiple destination transfers

Help wanted:

• Tor proxy support for RPC connection
• Multisig wallet operations
• Cold signing workflow
• Hardware wallet integration via RPC
• Integration test suite with stagenet

License

MIT – do whatever you want with it.

Acknowledgments

Built with love for the Monero community.

Inspired by Monerotopia 2026 and the simple idea that if AI agents are going to handle money, they should do it privately.

---

If you find this useful, consider donating XMR to support development:

45CGtczedKaT6gLHUd2FDebFjGpzio3FzB2AKtx82NxWPF99cfTMeJcCs1XhF9zJTLNVmd6chvMHSNb2symioZkp2f24nfK