Getting started

Quick start

Add the ROXI servers to an MCP client, connect your wallet, and make your first request.

Before you begin#

  • Node.js 20 or newer. Check with node -v. The servers run locally through npx.
  • An MCP client. This guide uses Claude Desktop; any client that supports stdio MCP servers works the same way.
  • MetaMask Mobile. You'll scan a QR code with it to connect, and approve transactions in it.

Set up#

  1. Open your client's MCP config

    In Claude Desktop, open Settings → Developer → Edit Config. The file lives at:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Add the ROXI servers

    Add all four, or only the ones you need. If the file already has servers, merge these into its mcpServers.

    claude_desktop_config.json
    {
  "mcpServers": {
    "metamask": { "command": "npx", "args": ["-y", "@roxi-os/metamask-mcp"] },
    "chainlist": { "command": "npx", "args": ["-y", "@roxi-os/chainlist-mcp"] },
    "erc20": { "command": "npx", "args": ["-y", "@roxi-os/erc20-mcp"] },
    "solc": { "command": "npx", "args": ["-y", "@roxi-os/solc-mcp"] }
  }
}

  3. Restart the client

    Quit and reopen Claude Desktop. The ROXI tools appear in the tools menu. The first start can take a little longer while npx downloads the packages.

  4. Connect your wallet

    Ask the agent:

    prompt
    Connect my MetaMask wallet.

    It shows a QR code. Scan it with MetaMask Mobile and approve the connection. See Connect a wallet for details.

  5. Make a first request

    Start with something read-only:

    prompt
    Switch to Sepolia and tell me my ETH balance.

    Switching networks asks for approval in MetaMask. The balance check needs no signature. You're set up.

Important. Practice on Sepolia (chain ID 11155111) before using mainnet. You can get test ETH from a Sepolia faucet. Every transaction still needs your approval, but testnet mistakes are free.

Run from source#

To run a server you've built yourself, for example while contributing, point the client at its build output with node instead of npx:

claude_desktop_config.json
{
  "mcpServers": {
    "metamask": {
      "command": "node",
      "args": ["/absolute/path/to/metamask-mcp/dist/index.js"]
    }
  }
}

metamask-mcp builds to dist/; chainlist-mcp, erc20-mcp and solc-mcp build to build/. Each server's page has its clone and build commands.

Troubleshooting

  • Tools don't appear. Check the config is valid JSON and that node -v is 20 or newer, then fully restart the client.
  • "Wallet not connected". Ask the agent to connect again; the session ends when the server stops.
  • No QR code shown. Some clients don't display images. Ask for the connect URI instead and open it on your phone.