orqus-mcp

MCP (Model Context Protocol) server for the Orqus blockchain. Provides AI-powered tools for querying chain state, managing OIP20 tokens, OIP451 policies, and debugging transactions.

Install

npm install @orqusio/orqus-mcp

Usage with Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "orqus": {
      "command": "npx",
      "args": ["@orqusio/orqus-mcp"],
      "env": {
        "ORQUS_RPC_URL": "https://rpc-test.orqus.io/"
      }
    }
  }
}

Or for development:

{
  "mcpServers": {
    "orqus": {
      "command": "npx",
      "args": ["tsx", "/path/to/orqus-mcp/src/index.ts"],
      "env": {
        "ORQUS_RPC_URL": "https://rpc-test.orqus.io/"
      }
    }
  }
}

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | ORQUS_RPC_URL | https://rpc-test.orqus.io/ | RPC endpoint URL |

All tools also accept optional rpcUrl and chainId parameters to override per-call.

Tools (19)

Chain & Block

| Tool | Description | |------|-------------| | chain_status | Latest block number, chain ID, base fee, gas limit | | get_block | Block details by number or hash |

Transaction

| Tool | Description | |------|-------------| | get_transaction | Transaction details, receipt, and decoded event logs | | debug_transaction | Revert reason analysis, fee breakdown, diagnostic hints |

Account & Fee Token

| Tool | Description | |------|-------------| | check_account | Fee token, balance, KYC status | | fee_token_info | Whitelist status, exchange rate, gas allowance | | set_fee_token | Set fee token for gas payment (pass 0x0 to clear) |

OIP20 Token (ERC20 superset)

| Tool | Description | |------|-------------| | token_info | Name, symbol, decimals, currency, supply, paused, policy | | create_token | Create token via OIP20 Factory (anyone can create) | | mint_token | Mint tokens (requires ISSUER_ROLE) | | transfer_token | Transfer tokens (subject to OIP451/OIP4512 compliance) | | approve_token | Approve token spending allowance |

OIP20 Roles (RBAC)

| Tool | Description | |------|-------------| | check_role | Check roles on a token (ADMIN, ISSUER, PAUSE, UNPAUSE, BURN_BLOCKED) | | grant_role | Grant a role (requires admin of that role) | | revoke_role | Revoke a role (requires admin of that role) |

OIP451 Policy & Compliance

| Tool | Description | |------|-------------| | compliance_check | OIP451 authorization + OIP4512 per-token KYC status | | create_policy | Create WHITELIST or BLACKLIST policy (anyone can create) |

Utility

| Tool | Description | |------|-------------| | create_wallet | Generate a new random wallet for testing | | get_wallet_address | Derive address from private key |

System Contract Addresses

| Contract | Address | |----------|---------| | OUSD (INNER_USD) | 0x6f20000000000000000000000000000000000000 | | FeeManager | 0x6ffe000000000000000000000000000000000000 | | TokenRateOracle | 0x6f6f000000000000000000000000000000000000 | | OIP451 Registry | 0x6f45100000000000000000000000000000000000 | | OIP4512 Compliance | 0x6f45120000000000000000000000000000000000 | | OIP20 Factory | 0x6ffc000000000000000000000000000000000000 |

Key Concepts

• No native token: Orqus uses OIP20 fee tokens for gas payment, not ETH
• Fee token model: eth_getBalance returns MAX; gas fees are deducted from OIP20 tokens via FeeManager
• OIP4512 KYC: Per-token, 0=not_passed (subject to tokenLimit), 1=passed (exempt)
• Exchange rate: token_per_USD scaled by 1e6 (e.g. 7820000 = 7.82 tokens per USD)
• Gas allowance: balance * 1e12 * 1e6 / (baseFee * rate)

License

MIT