convez.ai
MCP ServerIntegração & APIsAvançado
kreatospace

MCP Wallet Bridge

kreatospace/mcp-wallet-bridge

Ponte segura entre servidores MCP remotos e carteiras Web3 do usuário

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que conecta ferramentas Claude a carteiras Web3 do usuário (MetaMask, Phantom, WalletConnect) sem nunca acessar chaves privadas. Permite que agentes solicitam assinaturas de transações através de URLs de aprovação, mantendo o controle total nas mãos do usuário.

Instalação

$npx convez-ai kreatospace/mcp-wallet-bridge

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
1
Contribuidores
1

Casos de uso

  • Agentes que precisam executar transações blockchain com aprovação do usuário
  • Integração de MCP com DApps que requerem assinatura de transações
  • Fluxos de pagamento em Web3 mediados por Claude com controle de segurança

Veredito

Solução bem arquitetada que resolve um problema real em MCP + Web3: conectar agentes a carteiras sem comprometer segurança. Implementação sólida com suporte a múltiplas carteiras e transporte HTTP remoto, adequada para produção.

README

A tradução para o português deste README ainda está na fila.

mcp-wallet-bridge

The missing bridge between remote MCP servers and Web3 wallets.

MCP servers run on your backend. User wallets (MetaMask, Phantom, WalletConnect) live in the browser. This package connects them — without ever touching private keys.

Claude → MCP tool → wallet-bridge → Approval URL → User's wallet → Signed tx

The Problem

Every existing approach forces a bad tradeoff:

ApproachProblem
Private key in envAgent has full unsupervised access to funds
Custodial wallet (Coinbase AgentKit)You own the keys, not the user
mcp-wallet-signerstdio only — breaks with remote/HTTP MCP
Phantom MCP serverPhantom accounts only

@kreato-mcp/wallet-bridge works with remote MCP over HTTP (the transport used by claude.ai connectors, Claude Desktop remote servers, and any production deployment) and supports any wallet the user already has.


How It Works

  1. MCP tool is called → bridge creates a pending request in storage, returns an approvalUrl
  2. User opens the URL → sees a clear breakdown of what's being requested
  3. User approves in their wallet → MetaMask / Phantom popup appears, they confirm
  4. Your frontend calls bridge.resolve() → MCP tool can now confirm the action

No keys ever leave the user's wallet.


Install

# Core server SDK
npm install @kreato-mcp/wallet-bridge

# React UI component (optional)
npm install @kreato-mcp/wallet-bridge-ui

Quick Start

1. Initialize the bridge (MCP server)

import { createWalletBridge } from "@kreato-mcp/wallet-bridge";

export const bridge = createWalletBridge({
  approvalBaseUrl: "https://yourapp.xyz/wallet/approve",
  // storage: new PrismaAdapter(prisma),  // for production
  ttl: 600, // 10 minutes
});

2. Use it in any MCP tool

import { bridge, formatBridgeResult } from "@kreato-mcp/wallet-bridge";

// Inside your MCP tool handler:
server.tool("buy_product", async ({ productId, price }, ctx) => {
  const pending = await bridge.requestSignature({
    sessionId: ctx.user.id,
    transaction: {
      type: "transfer",
      chain: "base",
      to: "0xRecipient...",
      value: price,
      metadata: { productId, action: "buy_product" },
    },
  });

  return formatBridgeResult(pending);
  // Claude returns: "Please approve this transaction at: https://yourapp.xyz/wallet/approve/abc123"
});

3. Add the approval page (Next.js)

// app/wallet/approve/[id]/page.tsx
"use client";
import { WalletApproval } from "@kreato-mcp/wallet-bridge-ui";
import { useSendTransaction } from "wagmi";

export default function ApprovePage({ params }: { params: { id: string } }) {
  return (
    <WalletApproval
      requestId={params.id}
      appName="Your App"
      fetchRequest={async (id) => {
        const res = await fetch(`/api/wallet-bridge/requests/${id}`);
        return res.json();
      }}
      onApprove={async (request) => {
        // Sign with wagmi / viem / @solana/web3.js
        const hash = await sendTransaction({ ... });

        // Tell the bridge
        await fetch(`/api/wallet-bridge/resolve/${request.id}`, {
          method: "POST",
          body: JSON.stringify({ txHash: hash, signerAddress: address }),
        });
        return { txHash: hash, signerAddress: address };
      }}
      onReject={async (request) => {
        await fetch(`/api/wallet-bridge/reject/${request.id}`, { method: "POST" });
      }}
    />
  );
}

4. Add 3 API routes

// GET  /api/wallet-bridge/requests/[id]  → bridge.getRequest(id)
// POST /api/wallet-bridge/resolve/[id]   → bridge.resolve(id, result)
// POST /api/wallet-bridge/reject/[id]    → bridge.reject(id, reason)

See docs/examples/nextjs-api-routes.ts for the full implementation.


Storage Adapters

In-Memory (default)

Zero config. Good for development and single-process deployments.

const bridge = createWalletBridge({ approvalBaseUrl: "..." });

Prisma (production)

import { PrismaAdapter } from "@kreato-mcp/wallet-bridge/adapters/prisma";
import { prisma } from "./lib/prisma";

const bridge = createWalletBridge({
  approvalBaseUrl: "...",
  storage: new PrismaAdapter(prisma),
});

Add to your schema.prisma:

model McpWalletRequest {
  id          String    @id @default(cuid())
  sessionId   String
  transaction Json
  status      String    @default("pending")
  approvalUrl String
  createdAt   DateTime  @default(now())
  expiresAt   DateTime
  resolvedAt  DateTime?
  result      Json?
  error       String?

  @@index([sessionId])
  @@index([status, expiresAt])
}

Custom Adapter

Implement the StorageAdapter interface to use any database:

import { StorageAdapter, PendingRequest } from "@kreato-mcp/wallet-bridge";

class MyAdapter implements StorageAdapter {
  async create(req) { ... }
  async findById(id) { ... }
  async findBySession(sessionId) { ... }
  async update(id, patch) { ... }
  async delete(id) { ... }
  async cleanup(olderThan?) { ... }
}

Supported Chains

ChainIDFamily
EthereumethereumEVM
BasebaseEVM
Base Sepoliabase-sepoliaEVM
PolygonpolygonEVM
ArbitrumarbitrumEVM
OptimismoptimismEVM
SolanasolanaSolana
Solana Devnetsolana-devnetSolana

Custom chains: pass any string as chain in your transaction — the bridge stores it and passes it through to the approval UI.


Transaction Types

// Native token transfer
{ type: "transfer", chain: "base", to: "0x...", value: "0.01" }

// ERC-20 / SPL token
{ type: "token_transfer", chain: "base", to: "0x...", tokenAddress: "0x...", amount: "100" }

// Contract interaction
{ type: "contract_call", chain: "base", to: "0x...", abi: [...], functionName: "mint", args: [] }

// Message signing (no on-chain tx)
{ type: "sign_message", chain: "ethereum", message: "Sign in to YourApp" }

// EIP-712 typed data
{ type: "sign_typed", chain: "ethereum", domain: {...}, types: {...}, value: {...} }

Bridge API

// Create a pending request
bridge.requestSignature({ sessionId, transaction, ttl? })
  → { requestId, approvalUrl, expiresAt, status: "pending" }

// Get current status
bridge.getRequest(requestId)
  → PendingRequest | null

// Wait for resolution (long-polling)
bridge.waitForApproval(requestId, { pollInterval?, timeout? })
  → PendingRequest

// Resolve (called by your frontend after signing)
bridge.resolve(requestId, { txHash?, signature?, signerAddress })
  → PendingRequest

// Reject
bridge.reject(requestId, reason?)
  → PendingRequest

// List pending requests for a session
bridge.listPending(sessionId)
  → PendingRequest[]

// Clean up expired requests
bridge.cleanup()
  → number (count cleaned)

React Hooks

import {
  useWalletBridgeRequest,
  useBridgeApproval,
} from "@kreato-mcp/wallet-bridge-ui";

// Fetch + poll a request
const { request, loading, error, refetch } = useWalletBridgeRequest({
  endpoint: "/api/wallet-bridge/requests",
  requestId,
});

// Handle approve/reject actions
const { approve, reject, approving, phase } = useBridgeApproval({
  resolveEndpoint: "/api/wallet-bridge/resolve",
  rejectEndpoint: "/api/wallet-bridge/reject",
});

Apps Using This

  • Kreato — Web3 creator monetization platform

Add yours via PR.


Roadmap

  • Redis adapter
  • WebSocket push (instead of polling)
  • WalletConnect v3 deep-link support
  • Transaction simulation preview (via Tenderly / Alchemy)
  • Session key support (pre-authorized, scoped spending)
  • React Native / mobile approval UI

License

MIT

Ver o original no GitHub

Bom para

Relacionados