@mcp-dockmaster/mcp-cryptowallet-evm 1.0.0

package/.eslintrc/index.js

@@ -0,0 +1,12 @@
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended'
+  ],
+  rules: {
+    '@typescript-eslint/explicit-module-boundary-types': 'off'
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dcSpark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# MCP Crypto Wallet EVM
+
+This repository contains a Model Context Protocol (MCP) server that provides Claude with access to Ethereum and EVM-compatible blockchain operations via ethers.js v5. The server enables Claude to perform operations like creating wallets, checking balances, sending transactions, and interacting with smart contracts on EVM-compatible blockchains.
+
+## Overview
+
+The MCP server exposes the following tools to Claude:
+
+### Wallet Creation and Management
+- `wallet_create_random`: Create a new wallet with a random private key
+- `wallet_from_private_key`: Create a wallet from a private key
+- `wallet_from_mnemonic`: Create a wallet from a mnemonic phrase
+- `wallet_from_encrypted_json`: Create a wallet by decrypting an encrypted JSON wallet
+- `wallet_encrypt`: Encrypt a wallet with a password
+
+### Wallet Properties
+- `wallet_get_address`: Get the wallet address
+- `wallet_get_public_key`: Get the wallet public key
+- `wallet_get_private_key`: Get the wallet private key (with appropriate security warnings)
+- `wallet_get_mnemonic`: Get the wallet mnemonic phrase (if available)
+
+### Blockchain Methods
+- `wallet_get_balance`: Get the balance of the wallet
+- `wallet_get_chain_id`: Get the chain ID the wallet is connected to
+- `wallet_get_gas_price`: Get the current gas price
+- `wallet_get_transaction_count`: Get the number of transactions sent from this account (nonce)
+- `wallet_call`: Call a contract method without sending a transaction
+
+### Transaction Methods
+- `wallet_send_transaction`: Send a transaction
+- `wallet_sign_transaction`: Sign a transaction without sending it
+- `wallet_populate_transaction`: Populate a transaction with missing fields
+
+### Signing Methods
+- `wallet_sign_message`: Sign a message
+- `wallet_sign_typed_data`: Sign typed data (EIP-712)
+- `wallet_verify_message`: Verify a signed message
+- `wallet_verify_typed_data`: Verify signed typed data
+
+### Provider Methods
+- `provider_get_block`: Get a block by number or hash
+- `provider_get_transaction`: Get a transaction by hash
+- `provider_get_transaction_receipt`: Get a transaction receipt
+- `provider_get_code`: Get the code at an address
+- `provider_get_storage_at`: Get the storage at a position for an address
+- `provider_estimate_gas`: Estimate the gas required for a transaction
+- `provider_get_logs`: Get logs that match a filter
+- `provider_get_ens_resolver`: Get the ENS resolver for a name
+- `provider_lookup_address`: Lookup the ENS name for an address
+- `provider_resolve_name`: Resolve an ENS name to an address
+
+### Network Methods
+- `network_get_network`: Get the current network information
+- `network_get_block_number`: Get the current block number
+- `network_get_fee_data`: Get the current fee data (base fee, max priority fee, etc.)
+
+## Prerequisites
+
+- Node.js (v16 or higher)
+- Claude Desktop application
+
+## Installation
+
+### Option 1: Using npx (Recommended)
+
+You can run the MCP server directly without installation using npx:
+
+```bash
+npx @mcp-dockmaster/mcp-cryptowallet-evm
+```
+
+This will download and execute the server directly from npm.
+
+### Option 2: Manual Installation
+
+1. Clone this repository:
+   ```bash
+   git clone https://github.com/dcSpark/mcp-cryptowallet-evm.git
+   cd mcp-cryptowallet-evm
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm ci
+   ```
+
+3. Build the project:
+   ```bash
+   npm run build
+   ```
+
+## Configuration
+
+### Configure Claude Desktop
+
+To configure Claude Desktop to use this MCP server:
+
+1. Open Claude Desktop
+2. Navigate to the Claude Desktop configuration file:
+   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+   - Linux: `~/.config/Claude/claude_desktop_config.json`
+
+3. Add the MCP server configuration:
+
+```json
+{
+  "mcpServers": {
+    "mcp-cryptowallet-evm": {
+      "command": "npx",
+      "args": [
+        "@mcp-dockmaster/mcp-cryptowallet-evm"
+      ]
+    }
+  }
+}
+```
+
+Alternatively, if you installed the package locally:
+
+```json
+{
+  "mcpServers": {
+    "mcp-cryptowallet-evm": {
+      "command": "node",
+      "args": [
+        "/path/to/your/mcp-cryptowallet-evm/build/index.js"
+      ]
+    }
+  }
+}
+```
+
+### Running Locally
+
+```bash
+node build/index.js
+```
+
+## Usage
+
+Once configured, restart Claude Desktop. Claude will now have access to the Ethereum and EVM-compatible blockchain tools. You can ask Claude to:
+
+1. Create a new wallet:
+   ```
+   Can you create a new Ethereum wallet for me?
+   ```
+
+2. Check a wallet balance:
+   ```
+   What's the balance of the Ethereum wallet address 0x742d35Cc6634C0532925a3b844Bc454e4438f44e?
+   ```
+
+3. Send a transaction:
+   ```
+   Can you help me send 0.1 ETH to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e?
+   ```
+
+Claude will use the MCP server to interact with the Ethereum blockchain directly.
+
+## Development
+
+### Adding New Tools
+
+To add new tools to the MCP server:
+
+1. Define the tool in `src/tools.ts`
+2. Create a handler function in the appropriate handler file
+3. Add the handler to the `handlers` object in `src/tools.ts`
+
+### Building
+
+```bash
+npm run build
+```
+
+## License
+
+MIT

package/build/handlers/utils.d.ts

@@ -0,0 +1,29 @@
+import { ethers } from "ethers";
+import { ToolResultSchema } from "../types.js";
+/**
+ * Creates a success response with the given result
+ * @param result The result to include in the response
+ * @param message Optional message to include in the response
+ * @returns A ToolResultSchema with the result and message
+ */
+export declare const createSuccessResponse: <T>(result: T, message?: string) => ToolResultSchema<T>;
+/**
+ * Creates an error response with the given message
+ * @param message The error message
+ * @returns A ToolResultSchema with the error message
+ */
+export declare const createErrorResponse: (message: string) => ToolResultSchema<any>;
+/**
+ * Gets a provider from a provider URL
+ * @param providerUrl The provider URL
+ * @returns An ethers.js provider
+ */
+export declare const getProvider: (providerUrl?: string) => ethers.providers.Provider;
+/**
+ * Gets a wallet from a private key, mnemonic, or JSON wallet
+ * @param walletData The wallet data (private key, mnemonic, or JSON)
+ * @param password Optional password for encrypted JSON wallets
+ * @param provider Optional provider to connect the wallet to
+ * @returns An ethers.js wallet
+ */
+export declare const getWallet: (walletData: string, password?: string, providerUrl?: string) => Promise<ethers.Wallet>;

package/build/handlers/utils.js

@@ -0,0 +1,86 @@
+import { ethers } from "ethers";
+/**
+ * Creates a success response with the given result
+ * @param result The result to include in the response
+ * @param message Optional message to include in the response
+ * @returns A ToolResultSchema with the result and message
+ */
+export const createSuccessResponse = (result, message) => {
+    return {
+        content: [
+            {
+                type: "text",
+                text: message || "Operation completed successfully"
+            }
+        ],
+        isError: false,
+        toolResult: result
+    };
+};
+/**
+ * Creates an error response with the given message
+ * @param message The error message
+ * @returns A ToolResultSchema with the error message
+ */
+export const createErrorResponse = (message) => {
+    return {
+        content: [
+            {
+                type: "text",
+                text: message
+            }
+        ],
+        isError: true,
+        toolResult: { error: message }
+    };
+};
+/**
+ * Gets a provider from a provider URL
+ * @param providerUrl The provider URL
+ * @returns An ethers.js provider
+ */
+export const getProvider = (providerUrl) => {
+    if (!providerUrl) {
+        // Default to Ethereum mainnet if no provider URL is specified
+        return ethers.getDefaultProvider();
+    }
+    try {
+        return new ethers.providers.JsonRpcProvider(providerUrl);
+    }
+    catch (error) {
+        throw new Error(`Invalid provider URL: ${providerUrl}`);
+    }
+};
+/**
+ * Gets a wallet from a private key, mnemonic, or JSON wallet
+ * @param walletData The wallet data (private key, mnemonic, or JSON)
+ * @param password Optional password for encrypted JSON wallets
+ * @param provider Optional provider to connect the wallet to
+ * @returns An ethers.js wallet
+ */
+export const getWallet = async (walletData, password, providerUrl) => {
+    const provider = providerUrl ? getProvider(providerUrl) : undefined;
+    try {
+        // Try to parse as JSON first
+        if (walletData.startsWith("{")) {
+            if (!password) {
+                throw new Error("Password is required for encrypted JSON wallets");
+            }
+            const wallet = await ethers.Wallet.fromEncryptedJson(walletData, password);
+            return provider ? wallet.connect(provider) : wallet;
+        }
+        // Check if it's a mnemonic (12, 15, 18, 21, or 24 words)
+        const words = walletData.trim().split(/\s+/);
+        if ([12, 15, 18, 21, 24].includes(words.length)) {
+            const wallet = ethers.Wallet.fromMnemonic(walletData);
+            return provider ? wallet.connect(provider) : wallet;
+        }
+        // Assume it's a private key
+        const wallet = new ethers.Wallet(walletData);
+        return provider ? wallet.connect(provider) : wallet;
+    }
+    catch (error) {
+        throw new Error(`Invalid wallet data: ${error.message}`);
+    }
+};
+//# sourceMappingURL=utils.js.map

package/build/handlers/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/handlers/utils.ts"],"names":[],"mappings":"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"}

package/build/handlers/wallet.d.ts

@@ -0,0 +1,36 @@
+import { ToolResultSchema } from "../types.js";
+import { fromPrivateKeyHandlerInput, createMnemonicPhraseHandlerInput } from "./wallet.types.js";
+export declare const createWalletHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const fromPrivateKeyHandler: (input: fromPrivateKeyHandlerInput) => Promise<ToolResultSchema<any>>;
+export declare const createMnemonicPhraseHandler: (input: createMnemonicPhraseHandlerInput) => Promise<ToolResultSchema<any>>;
+export declare const fromMnemonicHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const fromEncryptedJsonHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const encryptWalletHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getAddressHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getPublicKeyHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getPrivateKeyHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getBalanceHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getChainIdHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getGasPriceHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getTransactionCountHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const callHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const sendTransactionHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const signTransactionHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const populateTransactionHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const signMessageHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const signTypedDataHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const verifyMessageHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const verifyTypedDataHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getBlockHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getTransactionHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getTransactionReceiptHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getCodeHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getStorageAtHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const estimateGasHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getLogsHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getEnsResolverHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const lookupAddressHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const resolveNameHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getNetworkHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getBlockNumberHandler: (input: any) => Promise<ToolResultSchema<any>>;
+export declare const getFeeDataHandler: (input: any) => Promise<ToolResultSchema<any>>;