dexe-mcp

<p align="center">
  <a href="https://www.npmjs.com/package/dexe-mcp">
    <img src="./assets/hero.svg" alt="dexe-mcp" width="100%"/>
  </a>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/dexe-mcp"><img alt="npm" src="https://img.shields.io/npm/v/dexe-mcp.svg?style=flat-square&labelColor=0b0f1e&color=9BB4FF"></a>
  <a href="https://nodejs.org"><img alt="node" src="https://img.shields.io/node/v/dexe-mcp.svg?style=flat-square&labelColor=0b0f1e&color=E07AFF"></a>
  <a href="https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/npm/l/dexe-mcp.svg?style=flat-square&labelColor=0b0f1e&color=FFC878"></a>
  <a href="https://modelcontextprotocol.io"><img alt="MCP-compatible" src="https://img.shields.io/badge/MCP-compatible-9BB4FF?style=flat-square&labelColor=0b0f1e"></a>
</p>

# dexe-mcp

An MCP (Model Context Protocol) server for [DeXe Protocol](https://dexe.io) governance on BNB Chain, with an additional generic surface for OpenZeppelin and Compound-Bravo Governor DAOs (Uniswap, Compound, Optimism).

It exposes 170 typed tools in 19 groups: DAO deployment, all 33 DeXe proposal types, voting, delegation, execution, OTC token sales, treasury and subgraph reads, one-call DAO reporting, IPFS metadata, transaction simulation, multi-agent orchestration, and diagnostics. Any MCP client that can launch a local command can use it — Claude Code, Claude Desktop, Cursor, Codex CLI, or a custom agent. The package also ships a **read-only edition**, `dexe-mcp-read` (54 tools that only read, on stdio or over HTTP for remote clients) — see [Read-only edition](#read-only-edition-dexe-mcp-read).

Writes are calldata-first: tools return a `{ to, data, value, chainId }` payload for your own wallet to sign. Broadcasting from the server is opt-in, and a human confirms every transaction: through WalletConnect (approved on your phone; no key on disk — the default) or an encrypted local keystore (each batch approved with its password on a local page). A plaintext hot key that signs unattended exists for bots and CI only, testnet by default. [docs/SIGNING.md](./docs/SIGNING.md) explains the modes and what each protects against.

<p align="center">
  <a href="#install-in-claude-code">Install</a> ·
  <a href="#quickstart-other-mcp-clients">Quickstart</a> ·
  <a href="#tool-catalog">Tool catalog</a> ·
  <a href="#environment-variables">Environment</a> ·
  <a href="https://github.com/edward-arinin-web-dev/dexe-mcp/tree/main/docs">Docs</a>
</p>

---

## Install in Claude Code

Two commands, typed inside Claude Code:

```
/plugin marketplace add edward-arinin-web-dev/dexe-mcp
/plugin install dexe@dexe-mcp
```

Then ask:

> "Show the treasury of `0x…` on BSC."

Reads work with no configuration: on-chain data, subgraphs, the DeXe backend, and IPFS all have public defaults, and WalletConnect signing is available immediately (`dexe_wc_connect`). Eight skills install with the plugin — `dexe-setup`, `dexe-create-dao`, `dexe-create-proposal`, `dexe-vote-execute`, `dexe-otc`, `dexe-staking`, `dexe-report` (zero-config), and `dexe-agent-team` (needs `DEXE_TOOLSETS=core,agents` and hot keys).

To create DAOs or proposals, or to broadcast transactions, run `/dexe-setup` — it walks through the two keys that unlock those paths (a Pinata token for IPFS uploads, a signer) and writes them to the `.env` the server actually loads (`~/.dexe-mcp/.env` for a plugin install).

Using Cursor, Claude Desktop, Codex CLI, another local MCP client, or the terminal? See [docs/INSTALL.md](./docs/INSTALL.md).

## Read-only edition (`dexe-mcp-read`)

A second binary in the same package serves only the 54 tools that read: DAOs, proposals, votes and voters, treasury, members, delegation, validators and experts, token sales, staking, protocol statistics, and external Governors. It cannot sign, send, upload or build transactions — that code is not even loaded into its process — and it keeps nothing between calls. It reads with zero configuration, and ignores and drops any signing or upload key it finds in a shared `.env`.

```bash
claude mcp add dexe-read -- npx -y -p dexe-mcp dexe-mcp-read      # Claude Code
```

```json
{ "mcpServers": { "dexe-read": { "command": "npx", "args": ["-y", "-p", "dexe-mcp", "dexe-mcp-read"] } } }
```

`dexe-mcp-read serve-http` serves the same tools over MCP Streamable HTTP for remote clients (Claude.ai custom connectors, ChatGPT developer mode); it ships as a Docker image recipe and is pre-release. Operators: [docs/REMOTE.md](./docs/REMOTE.md).

## Quickstart (other MCP clients)

Reads need no environment at all. The steps below set up uploads and signing.

**Wizard path:**

```bash
npx -y dexe-mcp@latest --version   # what you are about to run
npx -y dexe-mcp@latest init        # interactive setup: network, Pinata, signer mode
npx -y dexe-mcp@latest doctor      # verifies RPC, Pinata, IPFS gateway, subgraph
```

`--help` and `--version` print and exit without loading any environment. `init` writes `~/.dexe-mcp/.env` (a source checkout writes the repo-root `.env`) and prints a client-config snippet to paste. `doctor` checks every recognized `DEXE_*` variable and reports pass/warn/fail with remediation hints; **warnings are normal on a zero-config install** and it exits `0` — pass `--strict` (or set `DEXE_DOCTOR_STRICT=1`) to make warnings exit `1` in CI, and expect `2` on a real failure. Full runbook: [docs/SETUP.md](./docs/SETUP.md); check reference: [docs/DOCTOR.md](./docs/DOCTOR.md); upgrade notes: [docs/MIGRATION.md](./docs/MIGRATION.md).

Already installed globally? Use `dexe-mcp init` instead — **do not mix the two.** A global install shadows `npx dexe-mcp@<version>`, which then silently runs the old code ([docs/INSTALL.md](./docs/INSTALL.md)).

**Manual path** — register with your MCP client (`.mcp.json`, `claude_desktop_config.json`, Cursor settings):

```json
{
  "mcpServers": {
    "dexe": {
      "command": "npx",
      "args": ["-y", "dexe-mcp@latest"]
    }
  }
}
```

With a global install, the same block is `{ "command": "dexe-mcp" }`. Add an `env` block only if you want to override the defaults:

```json
{
  "mcpServers": {
    "dexe": {
      "command": "dexe-mcp",
      "env": {
        "DEXE_RPC_URL_MAINNET": "https://bsc-dataseed.bnbchain.org"
      }
    }
  }
}
```

The `env` block is optional — without it the server falls back to a public BSC RPC, which is rate-limited and suitable for evaluation; set your own endpoint for production use.

> **Windows:** if your MCP client can't resolve the `dexe-mcp` shim on PATH, point it at the script directly:
> `{ "command": "node", "args": ["<npm root -g>/dexe-mcp/dist/index.js"] }`

**Example calls** (all four are in the default profile — no `DEXE_TOOLSETS`, no env):

```jsonc
// The whole DAO in one call: identity, treasury, members, delegation,
// turnout, and everything with a deadline
dexe_dao_report({ govPool: "0x...", chainId: 56 })

// ...and on the next run, only what moved since the previous one
dexe_dao_report({ govPool: "0x...", chainId: 56, since: "last" })

// Enumerate every proposal type the server can build
dexe_proposal_catalog({ category: "all", implementedOnly: true })

// Create a proposal of ANY catalog type — proposalType + params
dexe_proposal_create({
  govPool:      "0x...",
  title:        "Pay the audit invoice",
  proposalType: "token_transfer",
  params:       { token: "0x...", recipient: "0x...", amount: "1000.0" }
})
```

`dexe_proposal_create` covers every on-chain catalog type; the single-purpose `dexe_proposal_build_*` builders (raw calldata, one tool per type) need `DEXE_TOOLSETS=core,proposals`.

Each write tool returns a `TxPayload` you pass to your wallet. To let the server broadcast instead, connect a wallet over WalletConnect (`dexe_wc_connect`), or create an encrypted key with `npx dexe-mcp key create` and set `DEXE_SIGNER_MODE=keystore` — each batch then opens a local approval page that asks for its password. That enables the composite flows `dexe_proposal_create`, `dexe_proposal_vote_and_execute`, and `dexe_tx_send`. A hot `DEXE_PRIVATE_KEY` signs only with `DEXE_SIGNER_MODE=unattended` (bots, CI); see [docs/SIGNING.md](./docs/SIGNING.md).

## Requirements

- Node.js ≥ 20.12 with a working `npm` (`process.loadEnvFile`, used to read `.env`, needs 20.12+). Check with `node -v`.
- Git — only for the optional dev toolset (`dexe_compile` / `dexe_test` / `dexe_lint`), which shallow-clones DeXe-Protocol on first use. Set `DEXE_PROTOCOL_PATH` to use an existing checkout. Reads, builders, and deploys do not use it.

## Features

- DeXe governance coverage: the 33 proposal types (24 external, 4 internal validator, 5 off-chain), validator chamber, expert delegation, multi-tier OTC sales with merkle whitelists.
- Calldata-first key model: no private key is required for any build tool. Broadcasting is a separate, explicit opt-in.
- Zero-config reads: public RPC, subgraph, backend, and IPFS gateway defaults let read tools work out of the box — including `dexe_dao_report`, which returns a whole DAO (identity, treasury, membership, delegation, turnout, deadlines) in one call, and can diff itself against its own previous run. [docs/REPORTING.md](./docs/REPORTING.md)
- External Governor support: 18 `dexe_gov_*` tools read, build, simulate, and decode against OpenZeppelin and Bravo Governors; new DAOs are a config entry.
- Multi-agent orchestration: run several wallets as personas against one DAO. `signerKey` on the write composites (`dexe_dao_create`, `dexe_proposal_create`, `dexe_proposal_vote_and_execute`, `dexe_tx_send`, the OTC buyer composites) chooses which keyring wallet signs; `dexe_agents_fund` previews a funding plan and only moves value on `confirm: true`, under an enforced per-agent cap and a rolling 24-hour spend budget; `dexe_agents_ledger` reports which persona did what and what it cost. **A fleet of hot keys sitting in `.env` is a loaded gun** — read [docs/AGENTS.md](./d