ResilientDB MCP Server
A Model Context Protocol (MCP) server for interacting with ResilientDB, a high-performance blockchain platform. This server allows Large Language Models (LLMs) like Claude to interact with ResilientDB through GraphQL queries and HTTP REST API.
Overview
This MCP server bridges the gap between AI agents (like Claude Desktop) and ResilientDB by providing a standardized interface for:
- GraphQL Operations: Asset transactions on the blockchain (port 8000)
- HTTP REST API Operations: Key-value storage operations (port 18000 - Crow server)
Note: For midterm, this implementation focuses on GraphQL and HTTP REST API integration. Smart contract operations (ResContract CLI) are temporarily disabled.
Features
GraphQL Operations (Port 8000)
createAccount: Create new accounts in ResilientDB (if supported)getTransaction: Retrieve asset transaction details by ID (blockchain transactions)postTransaction: Post new asset transactions to the blockchain (requires PrepareAsset with crypto keys)updateTransaction: Update existing transactions (note: blockchain transactions are typically immutable)
Key-Value Operations (Port 18000 - HTTP REST API)
get: Retrieve values by key using HTTP REST API (Crow server)set: Store key-value pairs using HTTP REST API (Crow server)
Note: For midterm, smart contract operations (compile, deploy, execute) are temporarily removed. Focus is on GraphQL and HTTP REST API integration.
Important Architecture Notes:
- GraphQL (port 8000): Used for blockchain asset transactions
- HTTP/Crow (port 18000): Used for key-value operations
Installation
Prerequisites
- Python 3.11 or higher
- ResilientDB instance running (see ResilientDB Installation)
- ResContract CLI installed (for smart contract operations)
- Access to ResilientDB GraphQL endpoint
Local Installation
- Clone the repository:
git clone https://github.com/rahulkanagaraj786/ResilientDB-MCP.git
cd ResilientDB-MCP
- Install dependencies:
pip install -r requirements.txt
- Configure environment variables:
cp .env.example .env
# Edit .env with your ResilientDB configuration
- Update
.envfile with your settings:
RESILIENTDB_GRAPHQL_URL=http://localhost:8000/graphql
RESILIENTDB_HTTP_URL=http://localhost:18000
Docker Installation
- Build the Docker image:
docker build -t mcp/resilientdb -f Dockerfile .
- Run the container:
docker run -i --rm mcp/resilientdb
Configuration
Environment Variables
| Variable | Description | Default |
|---|---|---|
RESILIENTDB_GRAPHQL_URL | GraphQL endpoint URL (port 8000 for asset transactions) | http://localhost:8000/graphql |
RESILIENTDB_HTTP_URL | HTTP/Crow server URL (port 18000 for KV operations) | http://localhost:18000 |
RESILIENTDB_API_KEY | Optional API key for authentication | None |
RESILIENTDB_AUTH_TOKEN | Optional auth token | None |
REQUEST_TIMEOUT | Request timeout in seconds | 30 |
TRANSACTION_POLL_INTERVAL | Polling interval for transactions | 1.0 |
MAX_POLL_ATTEMPTS | Maximum polling attempts | 30 |
Important Notes:
- GraphQL (port 8000) is used for asset transactions (blockchain)
- HTTP/Crow (port 18000) is used for key-value operations (simple storage)
Usage with Claude Desktop
Add the MCP server to your Claude Desktop configuration:
- Open Claude Desktop settings
- Edit the MCP servers configuration file (usually
claude_desktop.json) - Add the following configuration:
For Local Installation:
{
"mcpServers": {
"resilientdb": {
"command": "python",
"args": ["/path/to/ResilientDB-MCP/server.py"],
"env": {
"RESILIENTDB_GRAPHQL_URL": "http://localhost:8000/graphql",
"RESILIENTDB_HTTP_URL": "http://localhost:18000"
}
}
}
}
For Docker Installation:
{
"mcpServers": {
"resilientdb": {
"command": "docker",
"args": ["run", "-i", "--rm", "mcp/resilientdb"]
}
}
}
- Restart Claude Desktop
Available Tools
createAccount
Create a new account in ResilientDB.
Parameters:
accountId(optional): Account ID. If not provided, server will generate one.
Example:
{
"accountId": "my-account-123"
}
getTransaction
Get asset transaction details by transaction ID (GraphQL - port 8000).
Parameters:
transactionId(required): Transaction ID to retrieve
Example:
{
"transactionId": "tx-123456"
}
Note: This is for blockchain asset transactions, not KV transactions.
postTransaction
Post a new asset transaction to ResilientDB (GraphQL - port 8000).
Parameters:
data(required): Transaction data in PrepareAsset format with crypto keys and signatures
Example:
{
"data": {
"operation": "CREATE",
"asset": {
"data": {...}
},
"outputs": [...],
"inputs": [...]
}
}
Note: This requires PrepareAsset format with cryptographic keys. For simple KV operations, use the set tool instead.
updateTransaction
Update an existing transaction.
Parameters:
transactionId(required): Transaction ID to updatedata(required): Updated transaction data
Example:
{
"transactionId": "tx-123456",
"data": {
"status": "completed"
}
}
get
Retrieve a value from ResilientDB by key (HTTP REST API - port 18000).
Parameters:
key(required): Key to retrieve
Example:
{
"key": "my-key"
}
Note: This uses HTTP REST API (Crow server on port 18000).
set
Store a key-value pair in ResilientDB (HTTP REST API - port 18000).
Parameters:
key(required): Key to storevalue(required): Value to store (can be any JSON-serializable value)
Example:
{
"key": "my-key",
"value": "my-value"
}
Note: This uses HTTP REST API (Crow server on port 18000).
Architecture
The MCP server acts as a mediator between the MCP host (Claude Desktop) and ResilientDB backend services:
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Claude │────────▶│ MCP Server │────────▶│ ResilientDB │
│ Desktop │ │ (Python) │ │ Backend │
└─────────────┘ └──────────────┘ └─────────────┘
│
├──▶ GraphQL Client (port 8000)
│ (Asset Transactions only)
│
└──▶ HTTP REST Client (port 18000)
(Key-Value Operations)
Routing Logic
The server automatically routes requests to the appropriate service:
-
Asset Transactions → GraphQL API (port 8000)
getTransaction: Retrieve asset transactionspostTransaction: Post asset transactions (requires PrepareAsset)createAccount: Create accounts (if supported)updateTransaction: Update transactions (if supported)
-
Key-Value Operations → HTTP REST API (port 18000 - Crow server)
get: Retrieve key-value pairsset: Store key-value pairs
Important: KV operations use HTTP REST API (port 18000).
Development
Project Structure
ResilientDB-MCP/
├── server.py # Main MCP server implementation
├── graphql_client.py # GraphQL client for ResilientDB
├── rescontract_client.py # ResContract CLI client
├── config.py # Configuration management
├── requirements.txt # Python dependencies
├── Dockerfile # Docker configuration
└── README.md # This file
Running Tests
# Install test dependencies
pip install pytest pytest-asyncio
# Run tests
pytest
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
Troubleshooting
ResContract CLI Not Found
If you get an error about ResContract CLI not being found:
- Ensure ResContract CLI is installed
- Add it to your PATH, or
- Set
RESCONTRACT_CLI_PATHenvironment variable to the full path
GraphQL Connection Errors
If you encounter GraphQL connection errors:
- Verify ResilientDB is running
- Check the
RESILIENTDB_GRAPHQL_URLis correct (should be port 8000, not 9000) - Ensure network connectivity to the GraphQL endpoint
- Check firewall settings
- Verify GraphQL server is accessible:
curl http://localhost:8000/graphql
HTTP Connection Errors
If you encounter HTTP connection errors for KV operations:
- Verify Crow HTTP server is running on port 18000
- Check the
RESILIENTDB_HTTP_URLis correct - Test HTTP endpoint:
curl http://localhost:18000/v1/transactions/test - Ensure the HTTP server is accessible
Key-Value Operations Not Working
If KV operations (get/set) fail:
- Verify you're using HTTP REST API (port 18000), not GraphQL
- Check that Crow HTTP server is running
- Test with curl:
# Set a value curl -X POST -d '{"id":"test","value":"hello"}' http://localhost:18000/v1/transactions/commit # Get a value curl http://localhost:18000/v1/transactions/test - Verify HTTP REST API (port 18000) is accessible for KV operations
Transaction Timeouts
If transactions timeout:
- Increase
REQUEST_TIMEOUTin.env - Check ResilientDB blockchain status
- Verify network latency
Key Architecture Insights
Service Separation
ResilientDB uses different services for different operations:
-
GraphQL Server (Port 8000)
- Purpose: Blockchain asset transactions
- Operations:
getTransaction,postTransaction(with PrepareAsset)
-
HTTP/Crow Server (Port 18000)
- Purpose: Simple key-value storage
- Operations:
get,set(via REST API) - Endpoints:
POST /v1/transactions/commit(for set)GET /v1/transactions/{key}(for get)
Why This Matters
- KV operations use HTTP REST API (port 18000) for
set/getoperations - Asset transactions use GraphQL (port 8000) and require PrepareAsset format
- Wrong port numbers (e.g., 9000 instead of 8000) will cause connection errors
References
- ResilientDB GitHub
- ResilientDB Documentation
- ResilientDB GraphQL API
- ResilientDB Quick Start
- MCP Protocol Documentation
License
Apache 2.0 License
Authors
Team 10 - ECS 265 Project