{
  "markdown": "# DERO MCP server\n\n> **A read-only Model Context Protocol server for the DERO privacy blockchain** — a private-by-default Layer 1 with encrypted balances, private smart contracts (DVM-BASIC), and no public transaction graph. 21 daemon primitives + 12 composite tools (including TELA on-chain app inspection and dURL→SCID discovery), with a bundled documentation index spanning derod, tela, hologram, and deropay.\n\n[![MCP Registry](https://img.shields.io/badge/MCP-io.github.DHEBP%2Fdero--mcp--server-blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.DHEBP/dero-mcp-server)\n[![CI](https://github.com/DHEBP/dero-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/DHEBP/dero-mcp-server/actions/workflows/ci.yml)\n[![dero-mcp-server MCP server](https://glama.ai/mcp/servers/DHEBP/dero-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/DHEBP/dero-mcp-server)\n\n**Registry listing:** `io.github.DHEBP/dero-mcp-server` · **Version:** `0.6.0` · **Transports:** `stdio` (default, npm package) · `streamable-http` (`--http`, for self-hosting)\n\n---\n\n## What is an MCP server\n\nAn **MCP server** (Model Context Protocol) is a small program that gives your AI assistant — Claude Desktop, Cursor, OpenCode, ChatGPT with Custom Connectors — the ability to call specific tools on your behalf. Instead of the AI *talking* about DERO from memory, it can actually look things up: fetch a block, read a contract, search the docs, trace a transaction, estimate a deploy.\n\nYou install it once and point your AI host at it. From then on, every DERO question you ask in chat hits live chain data and the bundled docs corpus — not the AI's training cutoff.\n\n## What is DERO\n\nIf you're new to DERO: it's a privacy-first L1 blockchain — often described as a **private alternative to Ethereum** for builders who want smart contracts without a transparent ledger, or as a **Monero alternative** for users who want account-based privacy with native programmability instead of UTXO-only payments. Homomorphically encrypted balances. Ring signatures hide senders. Zero-knowledge range proofs (Bulletproofs) hide amounts. There is no public transaction graph. The current mainnet is **DERO Stargate**.\n\nFull docs: [derod.org](https://derod.org)\n\n## About this server\n\n[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that exposes **read-only and analysis** calls against a DERO Stargate **daemon** JSON-RPC endpoint. Ships as a stdio process for local MCP hosts (Claude Desktop, Cursor, OpenCode) or in **streamable-HTTP** mode behind a domain (e.g. `mcp.derod.org`) for ChatGPT Custom Connectors, Cursor hosted mode, and any agent that needs a remote URL. See [`deploy/`](./deploy/) for a reference self-hosted deployment.\n\n## Quick start\n\nGet a working DERO MCP connection in under 5 minutes.\n\n### What you need\n\n- **Node.js 20+** ([install](https://nodejs.org)) — verify with `node --version`.\n- **An MCP host** — Claude Desktop, Cursor, OpenCode, or ChatGPT with Custom Connectors. This walkthrough uses Claude Desktop; the JSON config below works identically in Cursor and OpenCode.\n- **Optional:** a local DERO daemon. If one is running on `127.0.0.1:10102`, the server detects and uses it automatically; otherwise it falls back to a public RPC, so it works with zero setup. Run your own for production — [how to](https://derod.org/basics/running-a-node.md).\n\n### 1. Open your MCP host's config\n\n| Host | Where |\n|---|---|\n| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Claude Desktop (Windows) | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Cursor | Settings → MCP → Add Server |\n| OpenCode | Settings → MCP → Add Server |\n| Codex CLI / IDE | `codex mcp add` or `~/.codex/config.toml` |\n\nCreate the file if it doesn't exist.\n\n### 2. Add the DERO MCP server\n\n```json\n{\n  \"mcpServers\": {\n    \"dero-daemon\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"dero-mcp-server\"]\n    }\n  }\n}\n```\n\nThis uses `npx` to fetch and run the latest published version — no manual install or build required.\n\nThe server **auto-detects a local node** at `127.0.0.1:10102`. To pin a specific daemon (custom port or a remote URL), add an `env` block:\n\n```json\n\"env\": { \"DERO_DAEMON_URL\": \"http://127.0.0.1:10102\" }\n```\n\n### 3. Restart your MCP host\n\nFully quit and reopen — not just refresh. MCP servers load at startup.\n\n### 4. Verify it works\n\nIn a new chat:\n\n> *\"What's the current DERO chain height?\"*\n\nA number back means you're connected. If you see an error, confirm the config file path is correct and your host was fully restarted (not just refreshed).\n\nOnce it's working, jump to [Try a prompt](#try-a-prompt) for a full tour.\n\n---\n\n## What you can do with it\n\nOnce installed, your MCP host can do all of these on your behalf — in natural language, no JSON-RPC needed:\n\n- **Inspect the chain** — blocks, transactions, mempool, encrypted balances, registered names\n- **Analyze smart contracts** — read code and state, classify the pattern, estimate deploy gas, pull relevant DVM-BASIC docs in one call\n- **Trace transactions** — look up any hash, confirm inclusion, classify the kind (transfer / SC install / SC call)\n- **Explore the on-chain web (TELA)** — discover apps by name (`vault.tela` → SCID), browse what's deployed, inspect an app's manifest and files, and read the actual on-chain HTML/JS/CSS — no separate indexer to run\n- **Search the docs** — across all four DERO sites (derod, tela, hologram, deropay)\n- **Run composite analyses** — chain health, claim audits, docs path recommendations, deploy pre-flights — each returns curated DERO docs citations alongside the data\n\n## Try a prompt\n\nAfter installing and restarting your MCP host, paste any of these. Start simple and work up.\n\n### Basic\n\nSingle-tool questions that verify the install and exercise live queries.\n\n> *\"What's the current DERO chain height?\"*\n>\n> *\"Resolve the DERO name 'engram' to an address.\"*\n>\n> *\"Find the documentation page on Bulletproofs.\"*\n>\n> *\"What does the smart contract at SCID 0000…0001 do?\"*\n\n### Intermediate\n\nComposite tools that fan out into multiple primitives and return a synthesized answer with citations.\n\n> *\"Explain the smart contract at SCID 0000000000000000000000000000000000000000000000000000000000000001 — what it does, its functions, and which DVM-BASIC docs are relevant.\"*\n>\n> *\"Trace transaction <hash> with full context — confirmation, classification, and what it touched.\"*\n>\n> *\"What's the right reading path for someone new to DERO smart contracts who wants to deploy a DVM-BASIC contract?\"*\n>\n> *\"Estimate the gas cost to deploy this DVM source: <paste contract>\"*\n\n### TELA — the decentralized web on DERO\n\nTELA apps are full web apps (HTML/CSS/JS) deployed entirely on-chain. The server discovers and reads them with no external indexer — the first discovery query runs a one-time ~15s scan, then it's instant.\n\n> *\"What's the SCID for vault.tela?\"*\n>\n> *\"What TELA apps exist on DERO? Show me a few.\"*\n>\n> *\"Inspect the TELA app at SCID <scid> — what is it, who made it, and what files does it have?\"*\n>\n> *\"Show me the actual HTML of that app's index.html.\"*\n\nFor multi-step agent recipes, per-tool guidance, error contract, and the composite-first rule, see [`SKILL.md`](./SKILL.md).\n\n**Not included (by design):** wallet RPC (`transfer`, `scinvoke`), `DERO.SendRawTransaction`, `DERO.SubmitBlock`. Those can move funds or consensus data; add them only with explicit user consent and a locked-down setup.\n\n## See also\n\n- [`SKILL.md`](./SKILL.md) — per-tool agent runbook: composite-first rule, structured error contract, citation rules, agent-loop recipes, port reference.\n- [`POSITIONING.md`](./POSITIONING.md) — who DERO MCP is for, who it isn't, comparison vs ACP / Stripe / Crossmint / Skyfire, privacy posture.\n\n## Requirements\n\n- Node.js **20+**\n- A reachable DERO daemon with RPC enabled (local node or your own remote URL).\n\n## Install & build\n\n```bash\ncd dero-mcp-server\nnpm install\nnpm run build\n```\n\nRun (auto-detects a local node at `127.0.0.1:10102`, else public fallback, when `DERO_DAEMON_URL` is unset):\n\n```bash\nnode dist/index.js\n```\n\nOr set an explicit URL (e.g. your local daemon):\n\n```bash\nDERO_DAEMON_URL=http://127.0.0.1:10102 node dist/index.js\n```\n\nDaemon resolution is **local-first**: with `DERO_DAEMON_URL` unset, the server uses a local node at `127.0.0.1:10102` if it answers, else the baked-in **third-party** public RPC (`82.65.143.182:10102`). Prefer your own node for privacy.\n\nStrip a trailing `/json_rpc` if you paste a full JSON-RPC URL — this server appends `/json_rpc`.\n\n## HTTP mode (self-hosted)\n\nFor clients that can't launch a local subprocess — ChatGPT Custom Connectors, Cursor hosted mode, n8n / Zapier integrations — run the server in streamable-HTTP mode and put it behind your own domain:\n\n```bash\nDERO_MCP_AUTH_TOKEN=$(openssl rand -base64 48) \\\n  dero-mcp-server --http\n# [dero-mcp-server] HTTP listening on 127.0.0.1:8787 (POST /mcp · GET /health)\n```\n\nBoth stdio and HTTP serve MCP `2026-07-28` and retain compatibility with 2025-era clients. HTTP exchanges are stateless and do not issue `Mcp-Session-Id`; 2026 clients negotiate through `server/discover`.\n\n| Variable | Default | Description |\n|---|---|---|\n| `DERO_MCP_HTTP` | unset | Set to `1` (or pass `--http`) to start in HTTP mode. |\n| `DERO_MCP_HTTP_PORT` | `8787` | Listen port. |\n| `DERO_MCP_HTTP_HOST` | `127.0.0.1` | Listen address. Use `0.0.0.0` to bind publicly (do not without auth + TLS upstream). |\n| `DERO_MCP_AUTH_TOKEN` | unset | If set, every `/mcp` request must carry `Authorization: Bearer <token>`. Constant-time compared. |\n\nFor a turnkey deploy with Caddy + auto-TLS + Docker Compose, see [`deploy/README.md`](./deploy/README.md). It's a self-hosting reference for `mcp.derod.org`-style instances — anyone can fork and run their own. The public default daemon behind a hosted instance may use an older `GetInfo` schedule formula than CalcSupply; `verify_supply` still treats the offline schedule number as authoritative (see [Verify the Supply](https://derod.org/integrity/verify-the-supply)).\n\nThe stdio transport (below) and the HTTP transport share the same underlying server factory, so the tool surface, response shapes, and error codes are identical across both.\n\n## Claude Desktop (same pattern for OpenCode and Cursor)\n\nAdd to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"dero-daemon\": {\n      \"command\": \"node\",\n      \"args\": [\"/ABSOLUTE/PATH/TO/dero-mcp-server/dist/index.js\"]\n    }\n  }\n}\n```\n\nOptional: add `\"env\": { \"DERO_DAEMON_URL\": \"http://127.0.0.1:10102\" }` to pin a specific daemon. Not needed if your local node uses the default port — the server auto-detects it.\n\nRestart Claude Desktop (or your OpenCode/Cursor host).\n\n## Cursor (or OpenCode)\n\nIn **Cursor Settings → MCP** (or OpenCode MCP settings), add a server that runs the same `command` / `args` / `env` as above.\n\n## OpenCode\n\nIn **OpenCode MCP settings**, add a server with the same `command` / `args` / `env` as above.\n\n## Codex\n\nCodex supports DERO MCP as either a local stdio server or a streamable-HTTP server. The stdio setup is simplest for local development because Codex launches the server process for each session.\n\nAdd the published npm package with:\n\n```bash\ncodex mcp add dero-daemon --env DERO_DAEMON_URL=http://127.0.0.1:10102 -- npx -y dero-mcp-server\n```\n\nReplace `http://127.0.0.1:10102` with your daemon base URL when using a custom host or port. Do not include `/json_rpc`; this server appends it.\n\nEquivalent `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.dero-daemon]\ncommand = \"npx\"\nargs = [\"-y\", \"dero-mcp-server\"]\n\n[mcp_servers.dero-daemon.env]\nDERO_DAEMON_URL = \"http://127.0.0.1:10102\"\n```\n\nA copyable example lives at [`.codex/config.example.toml`](./.codex/config.example.toml). Rename or copy it to `.codex/config.toml` only when you want a project-scoped Codex config; Codex loads project config only for trusted projects.\n\nFor an already-running streamable-HTTP deployment, add the URL instead:\n\n```bash\ncodex mcp add dero-daemon --url http://127.0.0.1:8787/mcp\n```\n\nIf the HTTP server requires a bearer token, store the token in an environment variable and add `--bearer-token-env-var DERO_MCP_AUTH_TOKEN`.\n\nRestart Codex or start a new session, then run `/mcp` to confirm `dero-daemon` is enabled. A simple verification prompt is:\n\n> *\"What's the current DERO chain height?\"*\n\n## Environment\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `DERO_DAEMON_URL` | *(local-first auto-detect)* | Daemon **base** URL (no `/json_rpc` required). Unset → local node at `127.0.0.1:10102` if reachable, else public fallback (`82.65.143.182:10102`). Set to pin a specific endpoint. |\n| `DERO_DOCS_ROOT` | bundled index | Optional dev override: path to a local `dero-docs` clone to index live MDX instead of the shipped bundle. |\n\n## Maintainer: bundled docs\n\nDocs tools read from `data/docs-index.json`, committed in this repo and shipped with the npm package. Rebuild the index when [dero-docs](https://github.com/DHEBP/dero-docs) changes:\n\n```bash\nnpm run release:docs-check\ngit add data/docs-index.json && git commit -m \"Refresh bundled docs index.\"\n```\n\nOr run **Refresh docs bundle** under [Actions](https://github.com/DHEBP/dero-mcp-server/actions/workflows/refresh-docs-bundle.yml) to open a PR. Pushes to `dero-docs` `main` can trigger that workflow via `repository_dispatch` when `MCP_DOCS_SYNC_TOKEN` is configured on the docs repo.\n\nAfter merging a bundle update: bump the patch version in `package.json` and `server.json`, then `npm publish --otp=...` and `mcp-publisher publish`.\n\n## Testing\n\n```bash\n# Check daemon connectivity\nnpm run doctor\n\n# MCP surface contract checks (tools/resources/prompts + error probe)\nnpm run smoke:mcp\n\n# Docs retrieval checks (bundled index — no clone required)\nnpm run smoke:docs\n\n# Run flow tests (10 RPC checks)\nnpm run test:flows\n\n# Typecheck\nnpm run typecheck\n```\n\nFlow tests run against the default public RPC. Set `DERO_DAEMON_URL` to test against your own daemon.\n\nCI runs on every push and PR — see `.github/workflows/ci.yml`.\n\n## Official MCP Registry\n\nPublish flow (maintainers):\n\n```bash\nmcp-publisher validate\nmcp-publisher login github\nmcp-publisher publish\n```\n\nVerify listing:\n\n```bash\ncurl \"https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.DHEBP/dero-mcp-server\"\n```\n\n## MCP Surface\n\n- **Tools (33):** 21 daemon read/analysis primitives + 12 composites, including `verify_supply` (offline CalcSupply), TELA app inspection (`tela_inspect`, `tela_get_doc_content`), TELA discovery (`dero_durl_to_scid`, `dero_tela_list_apps`), and docs retrieval (`dero_docs_search`, `dero_docs_get_page`, `dero_docs_list`)\n- **Resources (4):** `dero://mcp/server-info`, `dero://mcp/safety-boundary`, `dero://mcp/example-flows`, `dero://mcp/composites`\n- **Prompts (5):** `network_health_check`, `inspect_smart_contract`, `trace_transaction`, `find_dero_docs_for_intent`, `estimate_deploy_for_contract`\n\n## Error Contract\n\nWhen a tool call fails, the server returns a structured error payload in tool content:\n\n```json\n{\n  \"ok\": false,\n  \"tool\": \"dero_get_sc\",\n  \"_meta\": {\n    \"error\": {\n      \"code\": \"RPC_UNREACHABLE\",\n      \"hint\": \"Confirm daemon is running and reachable, then rerun `npm run doctor`.\",\n      \"retryable\": true,\n      \"raw\": \"fetch failed\"\n    }\n  }\n}\n```\n\nCommon `code` values:\n\n- `INVALID_INPUT`\n- `RPC_INVALID_PARAMS`\n- `RPC_METHOD_NOT_FOUND`\n- `RPC_HTTP_ERROR`\n- `RPC_UNREACHABLE`\n- `RPC_INVALID_RESPONSE`\n- `TOOL_EXECUTION_ERROR`\n\n## Roadmap\n\n- Optional wallet-RPC tools behind `DERO_ENABLE_WALLET_RPC=1` + separate URL.\n- Stricter typing / OpenAPI-derived tool schemas.\n- TELA-aware contract tooling (INDEX/DOC inspection, on-chain app discovery).\n\n## License\n\nMIT\n",
  "bytes": 15925,
  "sha": "60bb188398382528997c20219be3b837d06d9314b9029266f9048f816f339522",
  "repo_slug": "dhebp/dero-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dhebp_dero_mcp_server_a896f43f/readme"
}