Monero MCP server
Commit Nov 14, 2026Lets an AI client manage a Monero node and programmatic wallets to check balances, view history, and send XMR transactions.
Also known as psyb0t/docker-monero, docker-monero
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.2.4
- Last commit
- Nov 14, 2026
- License
- WTFPL
What is Monero MCP?
Monero lets an AI client manage a Monero node and programmatic wallets to check balances, view history, and send XMR transactions.
Summary generated from the project's README
About Monero MCP server
Managing a Monero node and programmatic wallets through an AI client is possible with this server. It bundles the official monerod and monero-wallet-rpc releases into a single container, providing an HTTP API and an MCP interface for agents to interact with the blockchain. Users can run this locally via Docker, requiring a DOCKER_MONERO_API_TOKEN for authentication.
Developers can use the tools to open wallets, check balances, view transfer history, and manage the wallet lifecycle. While the server can be configured for read-only access, the DOCKER_MONERO_MCP_ALLOW_TRANSFERS setting enables an MCP client to send XMR transactions. The setup also supports remote connections from wallets like Cake Wallet by serving a restricted RPC on port 18089.
This solution is designed for those needing an automated way to drive Monero operations. It includes built-in support for agent integrations like Claude Code, Codex, and OpenClaw. The node can run on a private regtest network for testing or on the mainnet, which requires significant disk space for the pruned blockchain.
What you can do with it
- 1Automated wallet balance inquiriesAn AI agent can check the current XMR balance of a specific wallet.
- 2Executing cryptocurrency transfersA developer can instruct an AI client to send Monero to a specific destination address.
- 3Monitoring transaction historyAn agent can retrieve a list of recent transfers and addresses associated with a wallet.
- 4Testing blockchain logic safelyDevelopers can use a private offline chain to test commands without using real funds.
Written from the project's README. Every use case is checked against a quote from it.
How to install Monero MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Monero MCP in Claude Code
$ claude mcp add docker-monero -- docker run -i --rm docker.io/psyb0t/monero:v0.2.4Install Monero MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"docker-monero": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/psyb0t/monero:v0.2.4"
]
}
}
}Install Monero MCP in VS Code
.vscode/mcp.json
{
"servers": {
"docker-monero": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/psyb0t/monero:v0.2.4"
]
}
}
}Install Monero MCP in VS Code CLI
$ code --add-mcp '{"name":"docker-monero","type":"stdio","command":"docker","args":["run","-i","--rm","docker.io/psyb0t/monero:v0.2.4"]}'Install Monero MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"docker-monero": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/psyb0t/monero:v0.2.4"
]
}
}
}Install Monero MCP in Codex
$ codex mcp add docker-monero -- docker run -i --rm docker.io/psyb0t/monero:v0.2.4Install Monero MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.docker-monero] command = "docker" args = ["run", "-i", "--rm", "docker.io/psyb0t/monero:v0.2.4"]
Install Monero MCP in Gemini CLI
$ gemini mcp add -s user docker-monero docker -- run -i --rm docker.io/psyb0t/monero:v0.2.4Install Monero MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"docker-monero": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/psyb0t/monero:v0.2.4"
]
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepsyb0t/docker-monero is public and reachablegithub.com/psyb0t/docker-monero ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)WTFPL is not OSI-approvedspdx.org/licenses/WTFPL.html ↗Finding
- Commit or release in the last yearLast commit or release 2026-11-10github.com/psyb0t/docker-monero ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubdocker-monero
Your own Monero node with programmatic wallets, in one container. It runs the official monerod and monero-wallet-rpc releases and puts an HTTP API and an MCP server in front of them, so scripts and AI agents can read the chain, open wallets, check balances, and send XMR. The node also serves the restricted RPC that Cake Wallet and other wallets connect to.
Contents
- What's inside
- Quick start
- Using the wallets
- Write switches
- Cake Wallet and other remote wallets
- MCP
- Agent integrations
- Configuration
- Documentation
- Development
- Sponsor
- License
What's inside
| Part | Does |
|---|---|
monerod |
The node. Syncs the chain, pruned by default. Restricted RPC on 18089 for remote wallets. |
monero-wallet-rpc |
One process per open wallet, started and stopped through the API. |
| HTTP API | /v1 on port 8080. Node state, wallet lifecycle, balances, addresses, transfer history, sends. |
| MCP server | /mcp on the same port, the same operations as tools for AI agents. |
| Metrics | Prometheus on port 9091. |
Binaries come from getmonero.org and are checked against pinned SHA-256 hashes at build time. The image runs as a non-root user and works with a read-only root filesystem.
Quick start
Try it on regtest first: a private offline chain where you mine blocks on demand, so nothing touches real money.
TOKEN=$(openssl rand -hex 32)
docker run -d --name monero \
-p 127.0.0.1:8080:8080 \
-e DOCKER_MONERO_API_TOKEN=$TOKEN \
-e DOCKER_MONERO_NETWORK=regtest \
psyb0t/monero
until curl -fs localhost:8080/ready >/dev/null; do
sleep 1
done
xmr() {
curl -s \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
"$@"
}
xmr -X POST localhost:8080/v1/wallets -d '{
"name": "alice",
"password": "pw"
}'
ADDR=$(
xmr localhost:8080/v1/wallets/alice/addresses |
jq -r .primaryAddress
)
xmr -X POST localhost:8080/v1/node/regtest/generate-blocks -d "{
\"count\": 100,
\"address\": \"$ADDR\"
}"
xmr localhost:8080/v1/wallets/alice/balance
For mainnet, use the compose file:
curl -LO https://raw.githubusercontent.com/psyb0t/docker-monero/main/docker-compose.yml
curl -L -o .env https://raw.githubusercontent.com/psyb0t/docker-monero/main/.env.example
# Set DOCKER_MONERO_API_TOKEN in .env. For the default DOCKER_MONERO_DATA_PATH:
mkdir -p ./data
sudo chown 10001:10001 ./data
docker compose up -d
The first mainnet sync takes days and about 105 GiB of disk pruned. GET /v1/node/info shows the progress.
Using the wallets
A wallet must be open to be read or spent from. Opening starts a wallet process, closing saves the wallet and stops it.
xmr -X POST localhost:8080/v1/wallets/alice/open -d '{
"password": "pw"
}'
# syncing? how far behind?
xmr localhost:8080/v1/wallets/alice/status
xmr -X POST localhost:8080/v1/wallets/alice/transfers -d '{
"destinations": [
{
"address": "4...",
"amount": "1500000000000"
}
],
"dryRun": true
}'
xmr -X POST localhost:8080/v1/wallets/alice/close
Amounts are strings of atomic units (1 XMR = 10^12). Sends are refused until the node and the wallet are both caught up, and dryRun prices a transaction without broadcasting it. Everything else is in the API docs and the OpenAPI spec at api/api.yml.
Write switches
Create or restore the wallets you need, then lock the deployment down:
DOCKER_MONERO_READ_ONLY=truerefuses every write: new or restored wallets, new subaddresses, sends. Opening, closing, and reading still work.DOCKER_MONERO_ALLOW_TRANSFERS=falserefuses only sends.DOCKER_MONERO_MCP_ALLOW_TRANSFERS=trueis the only way an MCP client can send. It is off by default.
Cake Wallet and other remote wallets
Publish port 18089 and point the wallet at http://<your-host>:18089 as a custom node. That is monerod's restricted RPC: it serves what wallets need and none of the commands that control the node. Set DOCKER_MONERO_PUBLIC_NODE=true if you also want to advertise it to the network.
To require a login, set DOCKER_MONERO_RPC_LOGIN=username:password and enter the same username and password in the wallet's custom node settings. Empty keeps login disabled. The rules for the value are in configuration.
MCP
Connect an MCP client to http://localhost:8080/mcp with Authorization: Bearer <token>. The tools and which ones each mode registers are in the MCP docs.
Agent integrations
An agent can drive a running instance through a skill and, for stdio-only MCP clients, a bridge plugin. Claude Code:
claude plugin marketplace add psyb0t/agents
claude plugin install monero@psyb0t
Codex, OpenClaw and plain MCP clients are covered in agent integrations. To change this repository, read AGENTS.md.
Configuration
All settings are DOCKER_MONERO_* environment variables, listed with defaults in the configuration docs. The only required one is DOCKER_MONERO_API_TOKEN. Compose mounts the host directory DOCKER_MONERO_DATA_PATH (default ./data) at /data. It must be writable by UID/GID 10001; back up its wallets subdirectory.
Give the container time to stop: it saves every open wallet and lets monerod flush its database. Use docker stop -t 180; the compose file sets stop_grace_period.
Documentation
The full documentation is at psyb0t.github.io/docker-monero.
| Page | What it covers |
|---|---|
| API | Amounts, wallet lifecycle, sync, sending, error codes |
| Configuration | Every variable, ports, disk |
| MCP | MCP tools |
| Agent integrations | Skill and plugins for Claude Code, Codex and OpenClaw |
| Security | What the service protects and what you have to |
| Monitoring | Probes, metrics, logs |
| Troubleshooting | Startup refusals and common API errors |
| Architecture | Processes, startup, shutdown, crash handling |
| Development | Building and testing from source |
Development
make build # static binary in build/
make test # unit tests
make test-api # the real image on regtest
make lint
Details in the development docs.
Sponsor
License
WTFPL. Monero itself is under its own BSD-3-Clause license.
Monero MCP questions
How do I add Monero MCP to Claude Code?
Run claude mcp add docker-monero -- docker run -i --rm docker.io/psyb0t/monero:v0.2.4 in your terminal. Add --scope user to make it available in every project.
How do I add Monero MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can an AI agent send Monero transactions?
Yes, but it must be explicitly enabled using the DOCKER_MONERO_MCP_ALLOW_TRANSFERS environment variable, as it is off by default.
How do I connect Cake Wallet to this server?
You can point Cake Wallet to the host on port 18089 as a custom node using the restricted RPC provided by monerod.
How much disk space is needed for a mainnet sync?
A mainnet sync requires approximately 105 GiB of pruned disk space.