klever-io/mcp-klever-vm

A Model Context Protocol (MCP) server tailored for Klever blockchain smart contract development. This server maintains and serves contextual knowledge including code patterns, best practices, and runtime behavior for developers working with the Klever VM SDK.
Features
- 🚀 **Triple Mode Operation**: Run as HTTP API server, MCP stdio server, or public hosted MCP server
- 💾 **Flexible Storage**: In-memory or Redis backend support
- 🔍 **Smart Context Retrieval**: Query by type, tags, or contract type
- 📝 **Automatic Pattern Extraction**: Parse Klever contracts to extract examples and patterns
- 🎯 **Relevance Ranking**: Intelligent scoring and ranking of context
- 🔄 **Live Updates**: Add and update context in real-time
- 🛡️ **Type Safety**: Full TypeScript with Zod validation
- 📚 **Comprehensive Knowledge Base**: Pre-loaded with Klever VM patterns, best practices, and examples
- 🔧 **Contract Validation**: Automatic detection of common issues and anti-patterns
- 🚀 **Deployment Scripts**: Ready-to-use scripts for contract deployment, upgrade, and querying
Quick Start
Install and run instantly via npx — no cloning required:
Or connect to the hosted public server:
See MCP Client Integration for client-specific configuration.
Architecture
Key Improvements Made
1. **Storage Layer**
- Added memory limits to prevent OOM in InMemoryStorage
- Optimized Redis queries to avoid O(N) KEYS command
- Added atomic transactions for Redis operations
- Improved error handling and validation
2. **API Security**
- Added input validation for all endpoints
- Batch operation size limits
- Proper error responses without leaking internals
- Environment-aware error messages
3. **Type Safety**
- Centralized schema validation
- Proper TypeScript interfaces for options
- Runtime validation of stored data
4. **Performance**
- Batch operations using Redis MGET
- Index-based queries instead of full scans
- Optimized count operations
Installation
1. Clone the repository:
2. Install dependencies:
3. Copy environment configuration:
4. Install Klever SDK tools (required for transactions):
5. Build the project:
Configuration
Edit .env file to configure the server:
MCP Client Integration
Claude Code
Claude Desktop
Add to your claude_desktop_config.json:
For detailed setup, see the Claude Desktop Installation Guide.
Cursor
Add to your Cursor MCP settings (.cursor/mcp.json):
VS Code (GitHub Copilot)
Add to .vscode/mcp.json in your project:
For detailed setup, see the VS Code Installation Guide.
Public MCP Server
The Klever MCP Server can be hosted as a public shared service, allowing any developer to connect without running it locally.
Connecting to the Public Server
Available Tools (Public Mode)
The public server exposes a read-only subset of tools for security:
| Tool | Description |
|------|-------------|
| query_context | Search the Klever VM knowledge base |
| get_context | Retrieve a specific context by ID |
| find_similar | Find contexts similar to a given context |
| get_knowledge_stats | Get knowledge base statistics |
| enhance_with_context | Enhance queries with relevant Klever VM context |
Write operations (add_context) and shell-based tools (init_klever_project, add_helper_scripts) are disabled in public mode.
Self-Hosting with Docker
Then connect:
Self-Hosting without Docker
Environment Variables (Public Mode)
| Variable | Default | Description |
|----------|---------|-------------|
| MODE | http | Set to public for hosted mode |
| PORT | 3000 | Server port |
| CORS_ORIGINS | _(unset)_ | Comma-separated allowed origins. Unset or * allows all origins |
| RATE_LIMIT_MCP | 60 | MCP endpoint requests/min per IP |
| RATE_LIMIT_API | 30 | API endpoint requests/min per IP |
| BODY_SIZE_LIMIT | 1mb | Max request body size |
Deployment Notes
For production at mcp.klever.org:
- Deploy Docker container behind a reverse proxy (nginx/Caddy/cloud LB) for TLS termination