{"id":49995058,"url":"https://github.com/dhebp/dero-mcp-server","last_synced_at":"2026-06-10T22:00:29.237Z","repository":{"id":358790748,"uuid":"1242969126","full_name":"DHEBP/dero-mcp-server","owner":"DHEBP","description":"Expose DERO daemon JSON-RPC as read-only Model Context Protocol tools for Cursor, Claude Desktop, and other MCP clients.","archived":false,"fork":false,"pushed_at":"2026-06-10T18:52:13.000Z","size":920,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-10T19:18:23.487Z","etag":null,"topics":["blockchain","cryptocurrency","privacy"],"latest_commit_sha":null,"homepage":"https://derod.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DHEBP.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-18T23:48:58.000Z","updated_at":"2026-06-10T18:54:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/DHEBP/dero-mcp-server","commit_stats":null,"previous_names":["dhebp/dero-mcp-server"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/DHEBP/dero-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DHEBP%2Fdero-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DHEBP%2Fdero-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DHEBP%2Fdero-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DHEBP%2Fdero-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DHEBP","download_url":"https://codeload.github.com/DHEBP/dero-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DHEBP%2Fdero-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34172196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","cryptocurrency","privacy"],"created_at":"2026-05-19T07:16:26.408Z","updated_at":"2026-06-10T22:00:29.222Z","avatar_url":"https://github.com/DHEBP.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DERO MCP server\n\n\u003e **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 + 9 composite tools (including TELA on-chain app inspection), 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.4.4` · **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\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\u003e *\"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- **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\u003e *\"What's the current DERO chain height?\"*\n\u003e\n\u003e *\"Resolve the DERO name 'engram' to an address.\"*\n\u003e\n\u003e *\"Find the documentation page on Bulletproofs.\"*\n\u003e\n\u003e *\"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\u003e *\"Explain the smart contract at SCID 0000000000000000000000000000000000000000000000000000000000000001 — what it does, its functions, and which DVM-BASIC docs are relevant.\"*\n\u003e\n\u003e *\"Trace transaction \u003chash\u003e with full context — confirmation, classification, and what it touched.\"*\n\u003e\n\u003e *\"What's the right reading path for someone new to DERO smart contracts who wants to deploy a DVM-BASIC contract?\"*\n\u003e\n\u003e *\"Estimate the gas cost to deploy this DVM source: \u003cpaste contract\u003e\"*\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 \u0026 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\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 \u003ctoken\u003e`. 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.\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## 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 \u0026\u0026 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 (30):** 21 daemon read/analysis primitives + 9 composites, including TELA app inspection (`tela_inspect`, `tela_get_doc_content`) 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhebp%2Fdero-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhebp%2Fdero-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhebp%2Fdero-mcp-server/lists"}