Skip to content
Back to search

epic-mcp

MCP server exposing Epic Cash node and wallet tools to LLM clients. Full-automation MCP server for Epic Cash node and wallet, with secret redaction.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/johanneshahn--epic-mcp/badge.svg)](/listings/johanneshahn--epic-mcp)

HTML

<a href="/listings/johanneshahn--epic-mcp"><img src="/api/listings/johanneshahn--epic-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

cd epic-mcp
npm install
npm run build
npm test

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 226 lines
  1. # epic-mcp
  2. An MCP (Model Context Protocol) server for **Epic Cash**. It exposes an Epic node and wallet as
  3. structured tools for LLM clients (OpenCode, Claude Desktop, …).
  4. - **Hybrid integration:** node via JSON-RPC v2 (`/v2/foreign`, `/v2/owner`), wallet via the
  5. `epic-wallet` CLI. The `epic client` subcommands are deliberately not exposed as tools because
  6. they require a TTY and do not work reliably over stdio.
  7. - **Read-only by default:** all state-changing tools are blocked until you explicitly set
  8. `EPIC_MCP_READ_ONLY=false`. Read tools run immediately; write/destructive tools carry the
  9. matching annotations.
  10. - **Network from config:** `chain_type` in `epic-server.toml` determines mainnet, floonet or
  11. usernet. When no config is supplied, mainnet is assumed (Epic's own default).
  12. - **No secret leaks:** the API secret, wallet password and recovery phrase are never returned to
  13. the client. Tools that reveal (`recover`) or generate (`init`) seeds are intentionally absent.
  14. ## Requirements
  15. - Node.js ≥ 20
  16. - `epic-wallet` on `PATH` (or an absolute path via `EPIC_MCP_WALLET_BIN`)
  17. - A running, reachable node HTTP API; for floonet, for example `epic --floonet`.
  18. The `epic` node binary is **not** spawned by this server.
  19. - An initialized wallet
  20. ## Install & Build
  21. ```sh
  22. cd epic-mcp
  23. npm install
  24. npm run build
  25. npm test
  26. ```
  27. ## Configuration
  28. All settings are supplied through environment variables. A template is available in
  29. `.env.example` (a `.env` file is **not** loaded automatically – set variables in the client or
  30. shell).
  31. | Variable | Default | Meaning |
  32. |---|---|---|
  33. | `EPIC_MCP_NODE_BIN` | `epic` | Currently unused – node access is HTTP-only; reserved for a possible CLI fallback |
  34. | `EPIC_MCP_NODE_URL` | from config, otherwise `3413` | Node API endpoint (highest priority) |
  35. | `EPIC_MCP_NODE_CONFIG` | – | Path to an `epic-server.toml`. Supplies `api_http_addr` (node URL) and `chain_type` (network). Works outside `~/.epic` as well. |
  36. | `EPIC_MCP_API_SECRET` | from `~/.epic/<chain-home>/.api_secret` | Basic auth secret |
  37. | `EPIC_MCP_WALLET_BIN` | `epic-wallet` | Wallet binary; bare name resolved via `PATH`, or an absolute path |
  38. | `EPIC_MCP_WALLET_PASSWORD` | – | Wallet password for unattended calls |
  39. | `EPIC_MCP_WALLET_ACCOUNT` | `default` | Account |
  40. | `EPIC_MCP_WALLET_NODE_URL` | – | `-r` for the wallet |
  41. | `EPIC_MCP_WALLET_DIR` / `EPIC_MCP_WALLET_CURRENT_DIR` | – | `-t` / `-c` |
  42. | `EPIC_MCP_READ_ONLY` | `true` | Blocks all state-changing tools (node and wallet); set to `false` to allow them |
  43. | `EPIC_MCP_MAX_SEND_AMOUNT` | – | Optional maximum per `wallet_send`/`wallet_pay`, in EPIC |
  44. | `EPIC_MCP_CLI_TIMEOUT_MS` | `60000` | Timeout per CLI call |
  45. | `EPIC_MCP_HTTP_TIMEOUT_MS` | `20000` | Timeout per HTTP call |
  46. | `EPIC_MCP_MAX_OUTPUT_CHARS` | `60000` | Output limit per tool response |
  47. > **Important:** `epic-wallet` accepts its password only as a `-p` argument or interactively.
  48. > For unattended automation it must therefore be provided as an environment variable. `-p` is
  49. > visible in the process list: run the server as a dedicated OS user and protect the
  50. > configuration with `chmod 600`. Alternatively, start the wallet in `owner_api` mode and switch
  51. > a future version of this server over to it.
  52. ### Binary discovery
  53. - **Node:** no `epic` binary is executed. The server talks JSON-RPC v2 to the HTTP endpoint
  54. resolved from `EPIC_MCP_NODE_URL`, then `api_http_addr` in `EPIC_MCP_NODE_CONFIG`, then
  55. `127.0.0.1:3413`. `EPIC_MCP_NODE_BIN` exists in the config schema but has no effect today.
  56. - **Wallet:** `EPIC_MCP_WALLET_BIN` defaults to the bare name `epic-wallet` and is passed to
  57. Node's `execFile` with an argument array (no shell). A bare name is looked up in the `PATH`
  58. **of the MCP server process**, which inherits the environment of the client that launched it
  59. (e.g. the OpenCode background service). If the client was started from a GUI and its `PATH`
  60. misses the wallet's install directory, set `EPIC_MCP_WALLET_BIN` to an absolute path instead.
  61. - If the binary cannot be found or executed, tools return
  62. `Binary "…" was not found or is not executable. Check EPIC_MCP_NODE_BIN / EPIC_MCP_WALLET_BIN or your PATH.`
  63. (that message mentions both variables for historical reasons; only `EPIC_MCP_WALLET_BIN` can
  64. affect binary lookup today).
  65. ## Client setup
  66. ### OpenCode V2
  67. In `~/.config/opencode/opencode.jsonc` (global) or `opencode.jsonc` in the project:
  68. ```jsonc
  69. {
  70. "$schema": "https://opencode.ai/config.json",
  71. "mcp": {
  72. "servers": {
  73. "epic": {
  74. "type": "local",
  75. "command": ["node", "/Users/johanneshahn/repos/epic-mcp/dist/index.js"],
  76. "environment": {
  77. "EPIC_MCP_NODE_CONFIG": "/Users/johanneshahn/.epic/main/epic-server.toml",
  78. "EPIC_MCP_WALLET_PASSWORD": "{env:EPIC_MCP_WALLET_PASSWORD}"
  79. },
  80. "codemode": false
  81. }
  82. }
  83. }
  84. }
  85. ```
  86. Then check with `opencode mcp list`. Tools are named `epic_wallet_get_info`, etc. Prompts are
  87. available as `/epic:epic-health-check`, etc.
  88. Note that `{env:NAME}` is resolved when OpenCode's background service starts. Restart the service
  89. after changing exported variables. The example sets `"codemode": false` so tools are exposed
  90. directly (`epic_node_get_tip`) instead of through Code Mode scripts. Remove it to use Code Mode.
  91. The server starts in **read-only** mode. To enable writes, add `"EPIC_MCP_READ_ONLY": "false"` to
  92. the `environment` block above (or set it in the shell before starting the client). The config
  93. guard applies to every write tool, including node tools such as `node_ban_peer`.
  94. ### Claude Desktop
  95. In `claude_desktop_config.json`:
  96. ```json
  97. {
  98. "mcpServers": {
  99. "epic": {
  100. "command": "node",
  101. "args": ["/Users/johanneshahn/repos/epic-mcp/dist/index.js"],
  102. "env": {
  103. "EPIC_MCP_NODE_CONFIG": "/path/to/epic-server.toml",
  104. "EPIC_MCP_WALLET_PASSWORD": "…"
  105. }
  106. }
  107. }
  108. }
  109. ```
  110. ## Tool overview
  111. ### Node
  112. | Tool | Purpose | Mode |
  113. |---|---|---|
  114. | `node_get_status` | Node status / sync | read |
  115. | `node_get_tip`, `node_get_version` | Tip and version | read |
  116. | `node_get_block`, `node_get_blocks`, `node_get_header` | Chain data | read |
  117. | `node_get_kernel`, `node_get_last_kernels` | Kernel lookup | read |
  118. | `node_get_outputs`, `node_get_unspent_outputs` | Outputs | read |
  119. | `node_get_pool` | Pool/stempool and unconfirmed transactions | read |
  120. | `node_get_peers` | Peers / onion addresses | read |
  121. | `node_validate_chain`, `node_get_block_template` | Validation / mining | read |
  122. | `node_ban_peer`, `node_unban_peer` | Peer management | write |
  123. | `node_push_transaction`, `node_submit_block` | Submit TX / block | write |
  124. | `node_compact_chain` | Database compaction | destructive |
  125. ### Wallet
  126. | Tool | Purpose | Mode |
  127. |---|---|---|
  128. | `wallet_get_info`, `wallet_get_address` | Balance / addresses | read |
  129. | `wallet_list_accounts`, `wallet_create_account` | Accounts | read / write |
  130. | `wallet_list_outputs`, `wallet_list_transactions` | Outputs / history | read |
  131. | `wallet_export_proof`, `wallet_verify_proof`, `wallet_export_tx` | Proofs / accounting | read |
  132. | `wallet_send`, `wallet_receive`, `wallet_finalize` | Transaction flow | write |
  133. | `wallet_invoice`, `wallet_issue_invoice`, `wallet_pay` | Invoice flow | write |
  134. | `wallet_post`, `wallet_repost`, `wallet_cancel` | Transaction management | write |
  135. | `wallet_scan` | Repair outputs against the node | write |
  136. | `wallet_import_tx` | Import transactions | write |
  137. | `wallet_change_password` | Change password | destructive |
  138. ### Bundles, resources, prompts
  139. - `epic_health_check` – status, version, tip, pool, peers (and optionally wallet) in one call
  140. - `epic_wallet_report` – balance, recent transactions and outputs as a report
  141. - Resources: `epic://node/status`, `epic://wallet/summary`, `epic://config`
  142. - Prompts: `/epic:epic-health-check`, `/epic:epic-wallet-report`, `/epic:epic-send-assistant`
  143. ## Security model
  144. 1. **Tool output is untrusted data.** Emoji strings, slates, transaction messages and block
  145. contents can contain prompt-injection-style text. Never interpret them as instructions. The
  146. server instructions point this out to the client.
  147. 2. **Secrets stay local.** `redact()` removes the API secret, password and lines containing
  148. seed/recovery/passphrase terms from every tool response.
  149. 3. **Read-only is the safe default.** State-changing tools return an error until
  150. `EPIC_MCP_READ_ONLY=false` is set explicitly. An LLM can spend money with `wallet_send`, so
  151. enabling writes should be a deliberate decision; consider `EPIC_MCP_MAX_SEND_AMOUNT` or client
  152. permissions as additional limits.
  153. 4. **No shell.** All CLI calls use `execFile` with argument arrays.
  154. 5. **Timeouts and output limits** prevent hanging processes and context overflow.
  155. ## Floonet quick test
  156. ```sh
  157. # 1. Start node and wallet on floonet (separate terminals)
  158. epic --floonet
  159. epic-wallet --floonet -p "<password>" -r http://127.0.0.1:13413 info
  160. # 2. Test the MCP server directly (stdio: JSON-RPC only on stdout)
  161. EPIC_MCP_NODE_CONFIG=/path/to/epic-server.toml EPIC_MCP_WALLET_PASSWORD='<password>' npm run dev
  162. ```
  163. `npm run dev` waits for JSON-RPC on stdin (debug logs go to stderr). For a quick smoke test
  164. without a client, `npm run check` (type check) and `npm test` are sufficient.
  165. ## Development
  166. ```sh
  167. npm run check # TypeScript
  168. npm test # Unit tests
  169. npm run build # dist/
  170. ```
  171. Layout:
  172. ```text
  173. src/
  174. ├── index.ts # McpServer + StdioServerTransport
  175. ├── config.ts # Environment config, secret handling
  176. ├── adapters/
  177. │ ├── cli.ts # execFile wrapper
  178. │ ├── node.ts # JSON-RPC v2 + REST
  179. │ └── wallet.ts # epic-wallet CLI
  180. ├── tools/
  181. │ ├── shared.ts # Tool registration + annotations
  182. │ ├── node.ts
  183. │ ├── wallet.ts
  184. │ └── composite.ts
  185. ├── resources.ts
  186. └── prompts.ts
  187. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.