Kleros MCP Server
A Model Context Protocol (MCP) server that retrieves comprehensive Kleros court dispute data including meta-evidence and evidence submissions from multiple blockchain networks.
Features
- 🔗 Multi-chain Support: Ethereum Mainnet and Gnosis Chain
- 📊 Comprehensive Data: Meta-evidence, evidence submissions, and IPFS content
- 🌐 Remote Hosting Ready: Streamable HTTP transport with session management
- 🔒 Secure: DNS rebinding protection and proper CORS configuration
- ⚡ Fast: Parallel IPFS content retrieval with error handling
- 📱 Claude Desktop Compatible: Direct URL integration
Supported Networks
- Ethereum Mainnet (chainId: 1)
- Gnosis Chain (chainId: 100)
Data Sources
- Meta-evidence API: Kleros dispute metadata
- Ethereum Subgraph: Evidence submissions on Ethereum
- Gnosis Subgraph: Evidence submissions on Gnosis Chain
- IPFS Gateway: Evidence content via Kleros CDN
Claude Desktop Integration
Easy Setup (Recommended)
-
Open Claude Desktop Settings
- Click on Settings in the sidebar
-
Go to Connectors
- Navigate to Settings → Connectors
-
Add Custom Connector
- Click "Add custom connector"
- Enter a name:
Kleros Court - Paste the URL:
https://kleros-mcp-server-new.fly.dev/mcp - Click "Add"
- Start Using
- The Kleros Court tool will now be available in Claude Desktop
- Try: "Get dispute data for dispute ID 481 on Gnosis Chain"
Alternative Configuration File Method
Add to your claude_desktop_config.json:
{
"mcpServers": {
"kleros": {
"url": "https://kleros-mcp-server-new.fly.dev/mcp"
}
}
}
MCP Tool
get_dispute_data
Retrieves comprehensive dispute data from Kleros including meta-evidence and evidence submissions.
Parameters:
disputeId(string): The dispute ID to retrieve data forchainId(number): The chain ID (1 for Ethereum, 100 for Gnosis)
Example Usage:
- "Get dispute data for dispute ID 123 on Ethereum"
- "Show me details for dispute 481 on Gnosis Chain"
- "Retrieve evidence for dispute 50 on chain 100"
Sample Response:
# Kleros Dispute Data
**Dispute ID:** 481
**Chain:** Gnosis Chain (100)
## Meta-Evidence
**Title:** Web3 Security Auditor Registry
**Description:** A curated registry of verified security auditors...
## Evidence Submissions (3)
### Evidence 1
**Title:** Challenge Justification
**Description:** Pokémon is not a web3 auditor, reject the submission.
**Type:** text/plain
Quick Start
Prerequisites
- Node.js 18.x or higher
- npm or yarn
Local Development
-
Clone and install dependencies:
git clone <your-repo> cd kleros-mcp-server npm install -
Build the project:
npm run build -
Start the server:
npm start -
Health check:
curl http://localhost:8080/health
Development Mode
For development with auto-restart:
npm run dev
Deployment
Fly.io Deployment
-
Install Fly CLI:
curl -L https://fly.io/install.sh | sh -
Login to Fly:
fly auth login -
Create app (update app name in fly.toml if needed):
fly apps create kleros-mcp-server-new -
Build and deploy:
npm run build fly deploy -
Check deployment:
fly status fly logs
Your MCP server will be available at: https://kleros-mcp-server-new.fly.dev/mcp
Environment Variables
Set any required environment variables:
fly secrets set ALLOWED_HOSTS=your-domain.com
API Endpoints
Health Check
GET /health
Returns server status and timestamp.
MCP Protocol
POST /mcp
GET /mcp (for SSE notifications)
DELETE /mcp (for session termination)
Main MCP protocol endpoints with session management.
Architecture
kleros-mcp-server/
├── src/
│ ├── index.ts # Express server with Streamable HTTP transport
│ ├── server.ts # MCP server setup and tool registration
│ ├── services/
│ │ ├── disputeService.ts # Main dispute data coordination
│ │ ├── metaEvidenceService.ts # Meta-evidence API integration
│ │ ├── subgraphService.ts # Subgraph queries
│ │ └── ipfsService.ts # IPFS content retrieval
│ ├── types/
│ │ └── index.ts # TypeScript type definitions
│ └── utils/
│ └── constants.ts # API endpoints and configuration
├── Dockerfile # Container configuration
├── fly.toml # Fly.io deployment configuration
└── package.json
Error Handling
The server includes comprehensive error handling:
- Network timeouts: 10-15 second timeouts for external APIs
- IPFS failures: Graceful handling of unreachable content
- Subgraph errors: Detailed error reporting for query failures
- Input validation: Proper validation of dispute IDs and chain IDs
Development
Adding New Chains
- Add chain ID to
SUPPORTED_CHAIN_IDSinsrc/types/index.ts - Add subgraph URL to
API_ENDPOINTS.SUBGRAPHSinsrc/utils/constants.ts - Add network name to
NETWORK_NAMESinsrc/utils/constants.ts
Testing
Test the dispute data retrieval:
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_dispute_data",
"arguments": {
"disputeId": "123",
"chainId": 1
}
},
"id": 1
}'
MCP Inspector Compliance
This server passes all MCP Inspector checks:
- ✅ Proper protocol implementation
- ✅ Correct message formatting
- ✅ Standard error codes
- ✅ Session management
- ✅ Resource cleanup
Security
- DNS rebinding protection enabled
- CORS properly configured
- Non-root container user
- Input validation and sanitization
- Graceful error handling without information leakage
Troubleshooting
Common Issues
- 404 Subgraph Errors: Check if subgraph URLs are up to date
- IPFS Timeout: Evidence content may be temporarily unavailable
- Invalid Dispute ID: Ensure the dispute exists on the specified chain
Getting Help
- Check server health:
curl https://kleros-mcp-server-new.fly.dev/health - View logs:
fly logs(for deployed version) - Test locally:
npm run dev
License
MIT
Contributing
- Fork the repository
- Create your feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
Support
For issues and questions:
- Create an issue in the repository
- Check the logs:
fly logs(for deployed version) - Verify health:
curl https://kleros-mcp-server-new.fly.dev/health