Walletbureau MCP

What walletbureau/mcp MCP server does

walletbureau/mcp MCP server provides behavioral risk information for wallet addresses on Base. Its primary operation, check_counterparty, evaluates the address using the recorded history of x402 and EIP-3009 USDC payments. The response includes a score from 0 to 100, a verdict of ok, caution, or avoid, and flags that explain the factors behind the result in plain language.

The report also contains aggregate activity data, such as when the address was first seen, inbound and outbound transaction counts, transfer volumes, distinct payers, and the basis used for confidence. Metadata identifies when the result was computed, how old the service cache is, the API version, and a disclaimer.

How it works

The package is a thin MCP wrapper around Wallet Bureau’s public HTTP API. Scoring and data collection happen remotely rather than in the package, so the server does not maintain its own scoring implementation or local cache. The remote service indexes Base payment activity and returns the report to the MCP client.

A check costs $0.01 when paid. Without credentials, the package uses a public free quota limited to a few checks per day per IP. A prepaid API key debits each check from an existing balance. Alternatively, an x402 wallet can pay $0.01 in USDC on Base for each request. If both payment credentials are configured, the prepaid key is selected.

Setup and configuration

Install the package with npm:

npm i @walletbureau/mcp --ignore-scripts

It ships runnable JavaScript and does not require a build step, native modules, or installation scripts. Configure it as a stdio MCP server by launching npx -y @walletbureau/mcp. The README provides examples for Claude Code, Claude Desktop, Cursor, and other MCP clients.

No environment variables are necessary for the free demo. Set WALLETBUREAU_API_KEY for prepaid usage, or set X402_PRIVATE_KEY to sign x402 payments. The latter is a real spending key and should belong to a dedicated wallet holding a small USDC balance. X402_MAX_PRICE_USD limits the price accepted for one paid request and defaults to 0.10. API_BASE_URL can point to another deployment; request and payment timeout variables control the relevant network budgets.

Tools and capabilities

The walletbureau/mcp MCP server exposes two tools:

• check_counterparty accepts a Base wallet address and returns the paid risk report. The client can see the price in the tool description and in _meta under walletbureau/pricing.
• get_service_stats takes no input and returns free public counters, including indexed addresses, ingested transfers, and served scores.

The check response has a stable schema: fields may be added, while renames or removals require a new API version. The server writes logs to stderr so stdout remains available for MCP protocol traffic.

Limitations and notes

The results are risk signals, not accusations or definitive judgments about an address. Coverage and conclusions depend on the payment history indexed by the remote service. The package itself has no independent scoring data and does not cache responses locally. A paid request may involve signing and on-chain settlement, so its payment timeout is longer than the default unpaid request timeout. The server is licensed under Apache-2.0.