A production-ready Model Context Protocol (MCP) server for the MIDL.js ecosystem. Enables LLMs to interact with Bitcoin and deploy smart contracts to MIDL L2 (Bitcoin-anchored EVM) in a safe, inspectable, and AI-native way.
- Install dependencies:
git clone https://github.com/Svector-anu/midl-mcp.git
cd midl-mcp
pnpm install-
Configure Claude Desktop with your mnemonic (see Configuration below)
-
Get test BTC from the MIDL Faucet (for regtest)
-
Start deploying: Just ask Claude to deploy a contract!
Full deployment guide: DEPLOY_AND_INTERACT.md Testing guide: FEATURE_TESTING_GUIDE.md Real example: EXAMPLE_DEPLOYMENT.md
deploy-contract-source- Compile & deploy Solidity (auto-resolves OpenZeppelin imports)call-contract- Call functions on deployed contracts (handles BTC anchoring)verify-contract- Verify source code on Blockscout explorer
get-wallet-balance- Check BTC balanceprepare-btc-transfer- Create unsigned PSBT for transfersbroadcast-transaction- Broadcast signed transactionsestimate-btc-transfer-fee- Calculate transaction costs
get-address-transactions- View transaction historyget-blockchain-info- Network status and infodecode-psbt- Inspect PSBT detailsvalidate-bitcoin-address- Validate address format
midl://balance/{address}- Current BTC balancemidl://utxos/{address}- Unspent transaction outputsmidl://fee-rates- Current network feesmidl://block-height- Current block heightmidl://network- Network configurationmidl://account- Connected account info
Add this to your claude_desktop_config.json:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"midl-bitcoin": {
"command": "npx",
"args": ["-y", "tsx", "/path/to/midl-mcp/src/index.ts"],
"env": {
"MIDL_NETWORK": "regtest",
"MIDL_MNEMONIC": "your twelve word mnemonic phrase here"
}
}
}
}| Variable | Description | Example | Required |
|---|---|---|---|
MIDL_NETWORK |
Bitcoin network | regtest, testnet, mainnet |
Yes |
MIDL_MNEMONIC |
Your wallet mnemonic (12 or 24 words) | word1 word2 word3 ... |
Yes |
MIDL_RPC_URL |
Optional custom RPC endpoint | https://mempool.space/testnet |
No |
Features:
- Automatic transaction signing
- Contract deployment
- Contract interaction
- BTC transfers
- Full read/write access
** Security Note:** Your mnemonic never leaves your machine. It's only used by the local MCP server to sign transactions. The MCP protocol ensures Claude cannot access environment variables directly.
- Replace
/path/to/midl-mcpwith your actual installation path - Use your real mnemonic from Xverse or another Bitcoin wallet
- Restart Claude Desktop completely (Cmd+Q on Mac, then reopen)
- Get test funds from https://faucet.regtest.midl.xyz (for regtest)
Ask Claude:
Deploy this contract:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract Counter {
uint256 public count;
function increment() public { count++; }
}
Ask Claude:
Call increment() on contract 0xYourContractAddress
Ask Claude:
What's my BTC balance?
Ask Claude:
How much would it cost to send 0.001 BTC to bcrt1q...?
See FEATURE_TESTING_GUIDE.md for 12 complete test scenarios.
MIDL is a Bitcoin-anchored EVM. Contract deployments require:
- BTC Transaction - Anchors the operation to Bitcoin
- EVM Transaction - Contains the contract bytecode
- BIP322 Signature - Links EVM tx to BTC txId
- Combined Submission - Both sent via
eth_sendBTCTransactions
The MCP server handles this complete flow automatically!
┌─────────────┐
│ Claude │ "Deploy this contract"
└──────┬──────┘
│
v
┌─────────────────────┐
│ MCP Server │
│ 1. Compile Solidity │ (resolves @openzeppelin imports)
│ 2. Create BTC tx │ (anchors to Bitcoin)
│ 3. Sign EVM tx │ (with BIP322)
│ 4. Submit both │ (eth_sendBTCTransactions)
│ 5. Verify contract │ (on Blockscout)
└──────┬──────────────┘
│
v
┌─────────────────────┐
│ MIDL L2 Network │
│ Bitcoin + EVM │
└─────────────────────┘
Run the test suite:
pnpm testManual testing with Claude Desktop:
# Follow the testing guide
cat FEATURE_TESTING_GUIDE.md- Faucet: https://faucet.regtest.midl.xyz
- Bitcoin Explorer: https://mempool.regtest.midl.xyz
- EVM Explorer: https://blockscout.regtest.midl.xyz
- EVM RPC: https://rpc.regtest.midl.xyz
- Bitcoin Explorer: https://mempool.space/testnet
- Faucet: Use external Bitcoin testnet faucets
- No Private Keys in Memory: The server never stores private keys
- Mnemonic-based Signing: Uses
@midl/nodefor secure transaction signing - Human-in-the-Loop: All actions require explicit user confirmation via Claude
- Testnet First: Defaults to testnet/regtest for safety
- Transparent Operations: All transactions are human-readable
The server uses a pre-connected wallet configuration model:
- Wallet connection established externally (via mnemonic)
- Server operates in read-only execution context for queries
- Write operations require explicit tool invocation
- MCP protocol prevents direct environment variable access
- Use testnet/regtest first before mainnet
- Review all transactions before confirmation
- Keep your mnemonic secure and never share it
- Use dedicated test wallets for development
- Verify contract addresses on block explorers
- Deployment Guide - Complete walkthrough
- Testing Guide - Test all 12 tools
- Real Example - Counter contract deployment
- MIDL JS SDK - Core SDK documentation
Solution: Check MIDL_MNEMONIC in Claude Desktop config
Solution: Get test BTC from https://faucet.regtest.midl.xyz
Solution: Wait 1-2 minutes for Bitcoin block confirmation
Solution: Ensure you're using MIDL_MNEMONIC in your configuration
Solution: Restart Claude Desktop completely (Cmd+Q on Mac, then reopen)
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Add tests for new features
- Submit a pull request
MIT
- GitHub: https://github.com/Svector-anu/midl-mcp
- MIDL Website: https://midl.xyz
- MIDL SDK: https://js.midl.xyz
- Documentation: https://js.midl.xyz/guides/deploy-contract
**Built for midl.xyz **