Content
<div align="center">
# 🔗 Casper Network MCP Server v0.1.0
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
[](https://cspr.live)
**Production-ready Model Context Protocol (MCP) server for Casper Network blockchain**
[Features](#-features) • [Quick Start](#-quick-start) • [Tools](#-available-tools) • [Prompts](#-prompts) • [Security](#-security) • [Contributing](#-contributing)
</div>
---
## 🚀 Features
### 🏗️ **Dual-Server Architecture**
- HTTP server (Express) for REST API access
- MCP stdio server for Claude Desktop integration
- Seamless communication between both servers
- Process management with graceful shutdown
- Health monitoring endpoints
### 🛠️ **Professional Structure**
- Modular tool system with separate tools.js
- Utility helpers in dedicated utils.js file
- Clean separation of concerns
- Easy to extend and maintain
- Production-tested components
### 🔧 **Developer-Friendly**
- Simple JSON-RPC interface
- Comprehensive error handling
- Environment-based configuration
- Docker containerization support
- MCP protocol 2024-11-05 implementation
- Zero-configuration deployment with sensible defaults
### 🎯 **Casper Network Integration**
- Wallet creation and management
- CSPR token transfers
- Staking and delegation operations
- Real-time blockchain data from mainnet
- Curated validator database (50+ top validators)
- Full integration with Casper JavaScript SDK
---
## 📦 Quick Start
### ✅ Prerequisites
```bash
# Required
Node.js >= 18.0.0
npm >= 9.0.0
# Casper Network API Key from cspr.cloud
# Get your free API key at: https://cspr.cloud
```
### 🔑 Configuration
Create a `.env` file with your Casper Network configuration:
- **CASPER_API_KEY:** Your API key from cspr.cloud (required)
- **CASPER_RPC_URL:** RPC endpoint (default: https://node.cspr.cloud/rpc)
- **CASPER_NETWORK_NAME:** Network name (default: casper for mainnet)
- **PORT:** HTTP server port (default: 8080)
- **CASPER_PRIVATE_KEY:** Optional default wallet private key (PEM format)
- **CASPER_PUBLIC_KEY:** Optional default wallet public key
### 📥 Installation
```bash
# Clone the repository
git clone https://github.com/Tairon-ai/casper-network-mcp.git
cd casper-network-mcp
# Install dependencies
npm install
# Configure environment
cp .env.example .env
# Edit .env and add your CASPER_API_KEY from cspr.cloud
# Start the HTTP server
npm start
# MCP stdio server for Claude Desktop
npm run mcp
```
### 🤖 Claude Desktop Integration
Add to your Claude Desktop configuration:
```json
{
"mcpServers": {
"casper-network": {
"command": "node",
"args": ["/path/to/casper-network-mcp/mcp/index.js"],
"env": {
"CASPER_API_KEY": "your_api_key_from_cspr_cloud",
"CASPER_RPC_URL": "https://node.cspr.cloud/rpc",
"CASPER_NETWORK_NAME": "casper"
}
}
}
}
```
> **Note:** Get your API key from https://cspr.cloud for mainnet access
---
## 🛠 Available Tools
### 📋 **Casper Network Blockchain Tools**
| Tool | Description | Parameters | Returns |
|------|-------------|------------|---------|
| `create_wallet` | Generate new ED25519 wallet | None | Public key, private key (PEM), account hash |
| `get_balance` | Check CSPR balance | `publicKey` (optional) | Balance in CSPR and motes |
| `get_account_info` | Get account details | `publicKey` (optional) | Account hash, keys, thresholds, purse |
| `transfer_cspr` | Send CSPR tokens | `toPublicKey`, `amount`, `transferId` (opt), `fromPrivateKeyPem` (opt) | Deploy hash, transaction details |
| `delegate_stake` | Delegate to validator | `validatorPublicKey`, `amount`, `delegatorPrivateKeyPem` (opt) | Deploy hash, staking details |
| `undelegate_stake` | Undelegate from validator | `validatorPublicKey`, `amount`, `delegatorPrivateKeyPem` (opt) | Deploy hash, unbonding info |
| `get_staking_rewards` | View staking info | `publicKey` (optional) | Total staked, delegations, validators |
| `get_validator_info` | Get validator details | `validatorPublicKey` | Name, stake, delegators, commission |
---
## 🤖 Prompts
### 💬 Example Prompts for AI Assistants
**Wallet Management:**
```
"Create a new Casper wallet for me"
"What's my CSPR balance?"
"Check the balance of wallet 01abc123..."
"Show me my Casper account details"
```
**Transfers:**
```
"Send 100 CSPR to wallet 01abc123..."
"Transfer 50 CSPR to 01def456... with transfer ID 12345"
```
**Staking:**
```
"Delegate 1000 CSPR to validator 012bac..."
"Stake 500 CSPR with Everstake validator"
"Undelegate 500 CSPR from validator 012bac..."
"Show me my staking rewards and delegations"
```
**Validator Info:**
```
"Tell me about Everstake validator 012bac..."
"What's the commission rate and total stake of validator 01c377...?"
"Find validators with 0% commission"
```
### 🔧 Testing Tools
```bash
# Test wallet creation
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "create_wallet", "arguments": {}}, "id": 1}'
# Test balance check
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_balance", "arguments": {"publicKey": "01abc..."}}, "id": 1}'
```
---
## 🔒 Security
### 🛡️ Security Best Practices
- **Private Key Protection** - Never commit `.env` files or private keys to version control
- **Environment Variables** - Store sensitive data (API keys, private keys) in environment variables
- **API Key Security** - Keep your cspr.cloud API key secure and don't share it
- **Input Validation** - All public keys and amounts are validated before processing
- **Mainnet Caution** - This server operates on Casper mainnet with real CSPR tokens
- **Error Handling** - Errors don't expose sensitive wallet information
- **Secure Communication** - All RPC calls use HTTPS to cspr.cloud
---
## 🚀 Deployment
### 🏭 Production Deployment
```bash
# Start production server
NODE_ENV=production npm start
# With PM2
pm2 start server.js --name casper-mcp
# With Docker
docker build -t casper-mcp .
docker run -d -p 8080:8080 --env-file .env casper-mcp
```
### 🔑 Environment Variables
```env
# Casper Network Configuration
CASPER_RPC_URL=https://node.cspr.cloud/rpc
CASPER_API_KEY=your_api_key_from_cspr_cloud
CASPER_NETWORK_NAME=casper
# Optional: Default Wallet
CASPER_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----
CASPER_PUBLIC_KEY=01abc123...
# Server Configuration
PORT=8080
NODE_ENV=production
```
---
## 🤝 Contributing
We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our development process.
```bash
# Fork the repository
git clone https://github.com/Tairon-ai/casper-network-mcp.git
# Create feature branch
git checkout -b feature/amazing-feature
# Make changes and commit
git commit -m 'feat: add amazing feature'
git push origin feature/amazing-feature
# Open Pull Request
```
---
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## 📚 Resources
- [MCP Protocol Specification](https://modelcontextprotocol.io/docs/getting-started/intro)
- [MCP GitHub Organization](https://github.com/modelcontextprotocol)
- [Casper Network Documentation](https://docs.casper.network/)
- [Casper JavaScript SDK](https://docs.casper.network/developers/dapps/sdk/script-sdk/)
- [cspr.live Explorer](https://cspr.live)
- [cspr.cloud RPC](https://cspr.cloud)
- [Express.js Documentation](https://expressjs.com/)
---
<div align="center">
**Built by [Tairon.ai](https://tairon.ai) team with help from Claude**
</div>
