Keystore MCP Server
A Model Context Protocol (MCP) server for Ethereum keystore encryption, decryption, and management following the Web3 Secret Storage Definition Version 3 standard.
Features
encrypt_keystore - Encrypt private key to Web3 Secret Storage V3 formatdecrypt_keystore - Decrypt keystore to recover private keysave_keystore_file - Save keystore with standard Ethereum namingload_keystore_file - Load and validate keystore filesget_keystore_info - Extract metadata without decryptionvalidate_keystore - Validate keystore structurechange_keystore_password - Change password and optionally upgrade KDFbatch_encrypt_keystores - Encrypt multiple walletskeystore_to_private_key_file - Export decrypted private key (dangerous)
Resources (4)
keystore://specification - Web3 Secret Storage V3 specificationkeystore://security-guide - Security best practiceskeystore://kdf-comparison - Scrypt vs PBKDF2 comparisonkeystore://examples/{type} - Example keystores
Prompts (4)
secure_wallet_backup - Guided backup creationkeystore_migration - Migration from legacy formatskeystore_recovery - Recovery assistancekeystore_security_audit - Security audit workflow
Installation
pip install -e .
pip install -e ".[dev]"
Usage
Running the Server
Claude Desktop Configuration
{
"mcpServers": {
"keystore": {
"command": "keystore-mcp-server"
}
}
}
Cryptographic Standards
Web3 Secret Storage V3
- KDF: scrypt (recommended) or pbkdf2
- Cipher: AES-128-CTR
- MAC: Keccak-256
- UUID: Version 4
Default Scrypt Parameters
| Parameter | Value | Description |
|---|
| N | 262144 (2^18) | CPU/memory cost |
| r | 8 | Block size |
| p | 1 | Parallelization |
| dklen | 32 | Derived key length |
Default PBKDF2 Parameters
| Parameter | Value | Description |
|---|
| c | 262144 | Iterations |
| prf | hmac-sha256 | PRF |
| dklen | 32 | Derived key length |
Security
⚠️ Important Security Notes:
- Never share keystore passwords - Treat like private keys
- Use strong passwords - Minimum 12 characters, mixed case, numbers, symbols
- Secure file storage - Files created with 0600 permissions
- Air-gapped operations - Use offline for high-value wallets
- Backup keystores - Store encrypted backups in multiple locations
Examples
Encrypt a Private Key
result = await encrypt_keystore(
private_key="0x...",
password="strong-password-123",
kdf="scrypt"
)
Decrypt a Keystore
result = await decrypt_keystore(
keystore=keystore_json,
password="strong-password-123"
)
Save Keystore File
result = await save_keystore_file(
keystore=keystore_json,
directory="./keystores"
)
Testing
License
MIT License