# Prover MCP
> **⚠️ Testnet Only**: This MCP is for Sepolia testnet only.
A Model Context Protocol (MCP) server that enables AI assistants to control Succinct Prover Network operations following the [official Succinct workflow](https://docs.succinct.xyz/docs/provers/running-a-prover/quickstart).
## Prerequisites
> **⚠️ Security Notice**: Use only fresh test wallets for Sepolia testnet. Never use mainnet private keys!
### Required Software
- **Node.js 18+** - [Download here](https://nodejs.org/)
- **Docker Desktop** - [Download here](https://docs.docker.com/get-started/get-docker/)
- ⚠️ Must be running before setup
### Required Blockchain Assets
1. **Fresh Ethereum Wallet**
- Create a new wallet (MetaMask, etc.)
- Get Sepolia ETH from [faucet](https://sepolia.etherscan.io/)
- Export private key (64 hex characters, no 0x prefix)
2. **PROVE Tokens**
- Get 1000+ PROVE tokens from [official faucet](https://docs.google.com/forms/d/e/1FAIpQLSfgTpBL_wMWyyoxT6LxuMhiu-bex0cBg9kRTmxoKw3XOluOCA/viewform)
- Minimum 1000 PROVE required for staking
## 🚀 Quick Setup
### Installation
```bash
git clone https://github.com/d3lta02/prover-mcp.git
cd prover-mcp
npm install
npm run build
```
### Setup Options
**Option 1: Interactive Setup (Recommended)**
```bash
npm run init
# Choose: Interactive Setup
# Select: AI client preference
# Optional: Add credentials during setup
```
**Option 2: Auto Setup (Fastest)**
```bash
npm run init
# Choose: Auto Setup
# Automatically configures detected AI clients
```
### Check Prover MCP & You're Ready
```bash
npm start
# Succinct Prover Network MCP Server running
```
Both methods create:
- 📄 `.env` file with configuration template
- 🤖 AI client MCP configurations (Claude/Cursor)
- 📋 Next steps following official Succinct workflow
## Configuration Methods
### Method 1: MCP Config (Recommended)
Environment variables are set directly in your AI client's MCP configuration:
**Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Cursor IDE**: `~/.cursor/mcp.json`
```json
{
"mcpServers": {
"succinct-prover": {
"command": "node",
"args": ["./build/index.js"],
"cwd": "/path/to/your/prover-mcp",
"env": {
"PROVER_ADDRESS": "your_prover_contract_address",
"PRIVATE_KEY": "your_64_character_private_key_no_0x_prefix"
}
}
}
}
```
### Method 2: Environment File
Edit the `.env` file created by setup:
```bash
# Edit with your real credentials
PROVER_ADDRESS=0x1234567890123456789012345678901234567890
PRIVATE_KEY=1234567890123456789012345678901234567890123456789012345678901234
```
> **💡 Pro Tip**: MCP config method bypasses tool cache issues and provides better reliability.
## Official Succinct Workflow
The setup follows the [official 5-step Succinct workflow](https://docs.succinct.xyz/docs/provers/running-a-prover/quickstart):
1. **✅ Requirements** (Automated by setup)
- Fresh Ethereum wallet with Sepolia ETH
- 1000+ PROVE tokens from faucet
- Docker Desktop running
2. **🏗️ Create Prover Contract** (Manual)
- Visit: https://staking.sepolia.succinct.xyz/prover
- Connect wallet & create prover
- Save prover address (different from wallet address!)
3. **💰 Stake PROVE Tokens** (Manual)
- Visit: https://staking.sepolia.succinct.xyz
- Stake minimum 1000 PROVE tokens
4. **⚙️ Calibrate Hardware** (AI Assisted)
- Command: *"Calibrate my prover hardware"*
5. **🚀 Run Prover** (AI Assisted)
- Command: *"Run Succinct Prover"*
## Usage After Setup
### Basic Commands
- 💬 **"Run Succinct Prover"** - Start the prover and earn PROVE tokens
- 💬 **"Calibrate my prover hardware"** - Optimize performance settings
- 💬 **"Show Succinct workflow"** - Check setup progress
- 💬 **"Get my prover status"** - View current earnings and performance
### Advanced Commands
- 💬 **"Get proof requests"** - View available proof requests
- 💬 **"Get my account balance"** - Check PROVE token balance
- 💬 **"Stop my prover"** - Gracefully stop the prover
## Manual Terminal Monitoring
For advanced users who want to monitor prover logs directly in terminal:
```bash
# Find your container ID
docker ps | grep succinct
# Stream live logs
docker logs -f CONTAINER_ID
# Monitor resource usage
docker stats CONTAINER_ID
```
> **💡 Note**: Replace CONTAINER_ID with your actual container ID. The MCP provides smart log viewing, but terminal monitoring offers real-time streaming for power users.
## How It Works
The MCP server provides secure access to Succinct Prover Network operations:
1. **Environment Loading**: Credentials loaded from MCP config (priority) or .env file
2. **Docker Integration**: Official Succinct Docker images with hardware optimization
3. **AI Commands**: Natural language interface to prover operations
4. **Security**: Sepolia testnet only, credentials never logged
The MCP configuration ensures environment variables are available to all tools, bypassing cache issues.
## Troubleshooting
### Common Issues
**❌ "Environment validation failed"**
- Ensure credentials are set in MCP config or .env file
- Restart your AI client completely after configuration changes
**❌ "Docker not found"**
- Install and start Docker Desktop
- Verify: `docker --version`
**❌ "Tool cache issues"**
- Use MCP config method instead of .env file
- MCP config bypasses tool cache limitations
**❌ "No PROVE tokens"**
- Get tokens from [official faucet](https://docs.google.com/forms/d/e/1FAIpQLSfgTpBL_wMWyyoxT6LxuMhiu-bex0cBg9kRTmxoKw3XOluOCA/viewform)
- Minimum 1000 PROVE required for staking
### Debug Commands
```bash
npm run validate # Validate installation
npm run init # Re-run setup process
npm test # Run test suite
```
## Security
> **🔒 CRITICAL SECURITY NOTES**
- **Testnet Only**: This MCP only works with Sepolia testnet
- **Fresh Wallets**: Use dedicated test wallets, never mainnet wallets
- **Private Keys**: Never commit credentials to version control
- **Official Sources**: Only use official Succinct URLs and contracts
All credential files are automatically git-ignored for security.
## Development
### Build
```bash
npm run build
```
### Testing
```bash
npm test
npm run validate
```
### File Structure
```
src/
├── index.ts # MCP server entry point
├── main.ts # CLI argument handling
├── cli/init.ts # Interactive setup tool
├── tools/prover/ # Prover network tools
├── tools/network/ # Network status tools
└── tools/monitoring/ # Performance monitoring
```
## Contributing
1. Fork the repository
2. Create feature branch: `git checkout -b feature-name`
3. Follow the [official Succinct documentation](https://docs.succinct.xyz/)
4. Test with Sepolia testnet only
5. Submit pull request
## Resources
- 📖 [Official Succinct Documentation](https://docs.succinct.xyz/)
- 🌐 [Succinct Prover Network](https://sepolia.succinct.xyz/)
- 💰 [PROVE Token Faucet](https://docs.google.com/forms/d/e/1FAIpQLSfgTpBL_wMWyyoxT6LxuMhiu-bex0cBg9kRTmxoKw3XOluOCA/viewform)
- 🏗️ [Prover Staking Interface](https://staking.sepolia.succinct.xyz/)
## License
MIT License - See LICENSE file for details.
---
**⚡ Ready to start earning PROVE tokens? Run `npm run init` and follow the setup!**
> **💡 Important**: The `cwd` (current working directory) parameter is automatically set by `npm run init` to ensure relative paths work correctly across different installations.
