Kleros Court MCP Server

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)

1. Open Claude Desktop Settings
   • Click on Settings in the sidebar
2. Go to Connectors
   • Navigate to Settings → Connectors
3. 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"

4. 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:

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 for
• chainId (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:

Quick Start

Prerequisites

• Node.js 18.x or higher
• npm or yarn

Local Development

1. Clone and install dependencies:
   git clone <your-repo> cd kleros-mcp-server npm install
2. Build the project:
   npm run build
3. Start the server:
   npm start
4. Health check:
   curl http://localhost:8080/health

Development Mode

For development with auto-restart:

Deployment

Fly.io Deployment

1. Install Fly CLI:
   curl -L https://fly.io/install.sh | sh
2. Login to Fly:
   fly auth login
3. Create app (update app name in fly.toml if needed):
   fly apps create kleros-mcp-server-new
4. Build and deploy:
   npm run build fly deploy
5. 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:

API Endpoints

Health Check

Returns server status and timestamp.

MCP Protocol

Main MCP protocol endpoints with session management.

Architecture

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

1. Add chain ID to SUPPORTED_CHAIN_IDS in src/types/index.ts
2. Add subgraph URL to API_ENDPOINTS.SUBGRAPHS in src/utils/constants.ts
3. Add network name to NETWORK_NAMES in src/utils/constants.ts

Testing

Test the dispute data retrieval:

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

1. 404 Subgraph Errors: Check if subgraph URLs are up to date
2. IPFS Timeout: Evidence content may be temporarily unavailable
3. 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

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. 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