kleros-scout-mcp-server by gmkung - MCP Server

Kleros MCP Server

A Model Context Protocol (MCP) server for querying address tags from the Kleros Scout API. Kleros Scout provides community-curated, decentralized address tags that help identify the trustworthiness and purpose of blockchain addresses across multiple EVM chains.

Features

🔍 Query Multiple Addresses: Look up tags for up to 100 addresses in a single request
🌐 Multi-Chain Support: Query across 20+ EVM chains simultaneously
📊 Flexible Output: Get results in JSON (machine-readable) or Markdown (human-readable) formats
✅ Verified Tags: Access community-curated and verified address information
🛡️ Type-Safe: Built with TypeScript and Zod validation
⚡ MCP Standard: Fully compliant with Model Context Protocol

What is Kleros Scout?

Kleros Scout is a decentralized, community-curated registry that provides:

Address Tags: Labels identifying address types (DEX, DeFi, Scam, etc.)
Project Names: Official names of protocols and smart contracts
Verification Status: Community-verified authenticity information
Metadata: Descriptions, websites, and additional context

This helps users identify trustworthy addresses and avoid malicious ones across the blockchain ecosystem.

Installation

# Clone or create the project directory
cd kleros-mcp-server

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Usage

The server can run in two modes:

1. Local Mode (stdio transport)

For local use with Claude Desktop using subprocess communication.

# Start the local server
npm start

Configuration for Claude Desktop:

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kleros": {
      "command": "node",
      "args": [
        "/absolute/path/to/kleros-mcp-server/dist/index.js"
      ]
    }
  }
}

2. Remote Mode (HTTP transport)

For remote access via HTTP/SSE, allowing others to use your server.

# Start the HTTP server
npm run start:http

# Or with custom configuration
PORT=3000 ALLOWED_ORIGINS=* npm run start:http

Configuration for Claude Desktop (remote):

{
  "mcpServers": {
    "kleros-remote": {
      "url": "https://your-server.com/mcp",
      "transport": "streamable-http"
    }
  }
}

🌐 Free Remote Hosting: See for step-by-step guides on deploying to:

Render.com (recommended, 750hrs/month free)
Railway.app ($5 credit/month)
Fly.io (3 free VMs)
Google Cloud Run (2M requests/month)

Setup time: ~5 minutes

Available Tools

`kleros_query_address_tags`

Query address tags for multiple addresses across multiple chains.

Parameters:

addresses (string[]): Array of Ethereum addresses (1-100)
- Format: 0x followed by 40 hexadecimal characters
- Example: ["0xed2d13a70acbd61074fc56bd0d0845e35f793e5e"]
chains (string[]): Array of EVM chain IDs (1-20)
- Common chains:
  - "1" - Ethereum Mainnet
  - "100" - Gnosis Chain
  - "137" - Polygon
  - "42161" - Arbitrum One
  - "10" - Optimism
  - "56" - Binance Smart Chain
  - "43114" - Avalanche C-Chain
  - "250" - Fantom
  - "324" - zkSync Era
  - "534352" - Scroll
  - "59144" - Linea
response_format ("json" | "markdown", optional): Output format
- Default: "markdown"

Example Usage:

// Query a single address on Ethereum and Gnosis
{
  "addresses": ["0xed2d13a70acbd61074fc56bd0d0845e35f793e5e"],
  "chains": ["1", "100"],
  "response_format": "markdown"
}

// Query multiple addresses on multiple chains
{
  "addresses": [
    "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
    "0x00000000000000ADc04C56Bf30aC9d3c0aAF14dC"
  ],
  "chains": ["1", "137", "42161"],
  "response_format": "json"
}

Response Formats

Markdown Format

Human-readable format with organized sections:

# Kleros Address Tags Query Results

**Total Results:** 2
**Query Time:** 2024-01-15T10:30:00.000Z

## Ethereum Mainnet (Chain ID: 1)

### 0xed2d13a70acbd61074fc56bd0d0845e35f793e5e

**Project:** Uniswap V3
**Tags:** DEX, DeFi, Liquidity Pool
**Description:** Uniswap V3 Router contract
**Website:** https://uniswap.org
**Verified:** ✓ Yes
**Submitted:** 2024-01-01T00:00:00.000Z

JSON Format

Machine-readable structured data:

{
  "totalResults": 2,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "1": {
      "0xed2d13a70acbd61074fc56bd0d0845e35f793e5e": {
        "address": "0xed2d13a70acbd61074fc56bd0d0845e35f793e5e",
        "chainId": "1",
        "tags": ["DEX", "DeFi", "Liquidity Pool"],
        "projectName": "Uniswap V3",
        "description": "Uniswap V3 Router contract",
        "website": "https://uniswap.org",
        "verified": true,
        "submittedAt": "2024-01-01T00:00:00.000Z"
      }
    }
  }
}

Error Handling

The server provides clear, actionable error messages:

Invalid Address Format: Guides on correct Ethereum address format
Invalid Chain ID: Explains chain ID requirements
Rate Limiting: Advises waiting before retry
Network Issues: Suggests checking connectivity
API Errors: Provides context about service status

Development

Project Structure

kleros-mcp-server/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── constants.ts          # Configuration constants
│   ├── types.ts              # TypeScript type definitions
│   ├── schemas/
│   │   └── address-tags.ts   # Zod validation schemas
│   ├── services/
│   │   ├── kleros-api.ts     # API client
│   │   └── formatter.ts      # Response formatters
│   └── tools/
│       └── query-address-tags.ts  # Tool implementation
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Build Commands

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run the server
npm start

# Development (build + run)
npm run dev

Adding New Features

To add new tools:

Create a new file in src/tools/
Define Zod schema in src/schemas/
Implement the tool handler
Register in src/index.ts

API Reference

Kleros Scout API

Base URL: https://scout-api.kleros.link

Endpoint: POST /api/address-tags

Request Body:

{
  "chains": ["1", "100"],
  "addresses": ["0x..."]
}

For more information, visit:

Limitations

Maximum 100 addresses per request
Maximum 20 chains per request
Response size limited to 25,000 characters
Rate limiting applies (managed by API)

License

MIT

Contributing

Contributions are welcome! Please ensure:

TypeScript strict mode compliance
Comprehensive error handling
Updated documentation
Zod schema validation for inputs

Support

For issues or questions:

Kleros Documentation: https://docs.kleros.io/
Kleros Discord: https://discord.gg/kleros
MCP Documentation: https://modelcontextprotocol.io/

Version History

1.0.0 (Initial Release)

Query address tags from Kleros Scout API
Multi-chain support for 11+ EVM chains
JSON and Markdown output formats
Comprehensive error handling
Type-safe implementation with Zod validation