MCP Mistcash

🚀 MCP Server for MIST.cash SDK

This is a Model Context Protocol (MCP) server that exposes the private payment functionality of MIST.cash on Starknet. It enables AI agents to interact with MIST.cash's privacy - preserving payment protocol through a standardized interface.

✨ Features

• 5 MCP Tools for transaction operations
• 2 MCP Resources for contract and transaction information
• Privacy First: Leverages MIST.cash's zero - knowledge proof system
• Multi - Token Support: ETH, USDC, USDT, DAI on Starknet
• Production - Ready: Comes with retry logic, timeouts, and comprehensive error handling

📋 Prerequisites

• Node.js 20 or higher (if running locally)
• Docker (recommended for teams)
• Access to a Starknet RPC provider (or a compatible Appchain)

🚀 Installation and Configuration

Option 1: Docker (Recommended for Teams)

This is the easiest way to ensure that everyone on the team has the same environment.

1. Build the image:

   docker build -t mcp-mistcash .
   

2. Run with Docker:

   To use it with MCP clients (such as Claude Desktop), you'll use the docker run command. Note the -i flag, which is required for stdio communication.

   docker run -i --rm \
     -e STARKNET_RPC_URL=https://ztarknet-madara.d.karnot.xyz \
     -e STARKNET_NETWORK=mainnet \
     -e CHAMBER_CONTRACT_ADDRESS=0xYourContractAddress \
     mcp-mistcash
   

Option 2: Local Development (Node.js)

1. Clone and install dependencies:

   cd mcp-mistcash
   npm install
   

2. Configure environment variables:

   Create a .env file based on the example:

   cp .env.example .env
   

   Edit the .env file with your configuration (example for Madara Appchain):

   STARKNET_RPC_URL=https://ztarknet-madara.d.karnot.xyz
   STARKNET_NETWORK=mainnet
   MCP_LOG_LEVEL=info
   # Optional: Chamber contract address (Required for Madara if not using Mainnet)
   # CHAMBER_CONTRACT_ADDRESS=0x...
   

3. Build the project:

   npm run build
   

🔌 Integration with AI Clients

To allow your team to use these tools in their daily work, they need to configure their preferred AI clients.

Claude Desktop

Add the following to your claude_desktop_config.json configuration file:

Configuration file path:

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

Docker Configuration (Recommended)

{
  "mcpServers": {
    "mist-cash": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "STARKNET_RPC_URL=https://ztarknet-madara.d.karnot.xyz",
        "-e", "STARKNET_NETWORK=mainnet",
        "mcp-mistcash"
      ]
    }
  }
}

Local Configuration (Alternative)

{
  "mcpServers": {
    "mist-cash": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-mistcash/dist/index.js"],
      "env": {
        "STARKNET_RPC_URL": "https://ztarknet-madara.d.karnot.xyz",
        "STARKNET_NETWORK": "mainnet"
      }
    }
  }
}

Cursor IDE

Add this to your MCP configurations in Cursor:

{
  "mist-cash": {
    "command": "docker",
    "args": [
        "run",
        "-i",
        "--rm",
        "-e", "STARKNET_RPC_URL=https://ztarknet-madara.d.karnot.xyz",
        "-e", "STARKNET_NETWORK=mainnet",
        "mcp-mistcash"
    ]
  }
}

💻 Usage Examples

Basic Usage

The following shows how to run the server using Docker:

docker build -t mcp-mistcash .
docker run -i --rm \
  -e STARKNET_RPC_URL=https://ztarknet-madara.d.karnot.xyz \
  -e STARKNET_NETWORK=mainnet \
  -e CHAMBER_CONTRACT_ADDRESS=0xYourContractAddress \
  mcp-mistcash

Advanced Usage

If you want to run the server locally with Node.js, you need to follow these steps:

cd mcp-mistcash
npm install
cp .env.example .env
# Edit the .env file with your configuration
npm run build

🛠️ Available Tools

1. generar_secreto_transaccion

Generates a cryptographic secret for a private transaction.

Parameters:

• claiming_key (string, required): Claim key for the transaction
• recipient_address (string, required): Starknet address (0x...)

2. obtener_assets_transaccion

Retrieves the assets of a transaction.

⚠️ Important Note

This function shows assets even if they have already been spent. Use verificar_existencia_transaccion for accurate verification.

Parameters:

• transaction_key (string, required): Key of the transaction to query
• recipient_address (string, required): Starknet address of the recipient
• provider_rpc_url (string, optional): Custom RPC URL

3. verificar_existencia_transaccion

Verifies if a transaction with specific assets exists. Ideal for completely private transactions.

Parameters:

• claiming_key (string, required): Claim key
• recipient (string, required): Address of the recipient
• token_address (string, required): Address of the token contract
• amount (string, required): Amount in base units (wei)

4. calcular_hash_transaccion

Calculates the unique hash of a transaction.

Parameters:

• transaction_key (string, required): Key of the transaction
• recipient_address (string, required): Address of the recipient
• token_address (string, required): Address of the token
• amount (string, required): Amount in base units

5. obtener_configuracion_chamber

Retrieves the configuration of the Chamber contract and the supported tokens.

Parameters:

• network (enum, optional): "mainnet" or "sepolia" (default: "mainnet")

📚 Available Resources

chamber://contract-info

Static information about the MIST.cash Chamber contract, including ABI, addresses, and features.

chamber://tx/{txHash}

Details for a specific transaction by hash.

🔒 Security Considerations

✅ Secure Practices

• No Private Keys: Only handles public claim keys
• Address Validation: All Starknet addresses are validated
• Secure Logging: Transaction secrets are never logged
• Input Validation: All inputs are validated by Zod schemas

⚠️ Important Warnings

1. Spent Transactions: obtener_assets_transaccion does not detect spent assets
2. RPC Costs: Monitor RPC usage to avoid unexpected costs
3. Network Delays: 30 - second timeout on all contract calls

🏗️ Project Structure

mcp-mistcash/
├── src/
│   ├── index.ts                 # Main MCP server
│   ├── types.ts                 # TypeScript type definitions
│   ├── tools/                   # Tool implementations
│   ├── resources/               # MCP resources
│   └── utils/                   # Utilities (provider, validation)
├── Dockerfile                   # Configuration for building the Docker image
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

🤝 Contributions

Contributions are welcome. Please ensure that:

1. All tools have proper error handling
2. Zod schemas validate inputs
3. The code follows TypeScript best practices
4. The documentation is up - to - date

📄 License

MIT

Built with ❤️ for the Starknet and MCP communities