Minima MCP
MCP server: Minima MCP
Installation
npx minima-mcpAsk AI about Minima MCP
Powered by Claude Β· Grounded in docs
I know everything about Minima MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Minima MCP
Model Context Protocol Server for Minima Blockchain
Production-ready MCP server enabling Large Language Models to securely interact with the Minima blockchain through standardized tools, autonomous agent orchestration, and multi-model inference.
Overview
Minima MCP enables Large Language Models to interact with the Minima blockchain through a secure, standardized Model Context Protocol interface. It provides 27 tools for blockchain operations, autonomous agent orchestration, and multi-model inference.
What is MCP?
Model Context Protocol is an open standard created by Anthropic that allows AI systems to securely connect to external tools and data sources. This implementation provides blockchain-specific tools for Minima.
Key Features
Blockchain Operations
- Transaction management (send, receive, search)
- Token creation and validation
- Smart contract execution
- P2P messaging via Maxima
- Vault operations and time-locks
Security
- OAuth 2.1 authentication
- API key management
- Rate limiting and transaction limits
- Comprehensive audit logging
- Input validation
AI Integration
- Google Gemini 3 Pro integration
- Script analysis and explanation
- Security auditing
- Token distribution optimization
Production Infrastructure
- Prometheus metrics
- Docker deployment
- Health monitoring
- Comprehensive error handling
Prerequisites
System Requirements
- Node.js >= 18.0.0
- Java >= 11 (for Minima node)
- RAM >= 2GB
- Disk >= 5GB for blockchain data
Minima Node
Before running the MCP server, you need a Minima node running and accessible.
Download Minima:
Visit minima.global to download the Minima node software, or:
curl -O https://github.com/minima-global/Minima/releases/latest/download/minima.jar
Start the node:
# Basic startup for development
java -jar minima.jar -data .minima -rpcenable
# Production startup (connects to network)
java -jar minima.jar -data .minima -p2pnodes megammr.minima.global:9001 -rpcenable
# With MDS (Minima DApp System)
java -jar minima.jar -data .minima -mdsenable -mdspassword YOUR_PASSWORD -rpcenable
Verify node is running:
curl http://localhost:9005/status
Important Notes:
- Port 9005 is the RPC API endpoint
- The node must be running for the MCP server to function
- Use
-cleanflag only for first-time setup (wipes all data)
Installation
# Clone the repository
git clone https://github.com/furcateresearch/minima-mcp.git
cd minima-mcp
# Install dependencies
npm install
# Configure environment
cp .env.example .env
# Edit .env with your configuration
# Build the project
npm run build
Configuration
Edit .env file:
# Minima Node Configuration
MINIMA_HOST=localhost
MINIMA_PORT=9005
# Google Gemini AI (optional - for AI-powered features)
GOOGLE_API_KEY=your_google_api_key_here
# Authentication
JWT_SECRET=your_jwt_secret_here
DEFAULT_API_KEY=your_default_api_key_here
# Server Configuration
NODE_ENV=development
MCP_PORT=3000
METRICS_PORT=9090
LOG_LEVEL=info
# Security - Rate Limiting
RATE_LIMIT_MAX_REQUESTS=100
MAX_TRANSACTION_AMOUNT=1000000
DAILY_LIMIT=10000000
Usage
Starting the MCP Server
npm run start
The server starts in stdio mode and listens for MCP protocol messages.
Health Check:
curl http://localhost:9090/health
Metrics:
curl http://localhost:9090/metrics
Docker Deployment
# Start all services (Minima node, MCP server, Redis, Prometheus, Grafana)
docker-compose up -d
# Check health
curl http://localhost:9090/health
# View logs
docker-compose logs -f
# Stop services
docker-compose down
Available Tools
The MCP server provides 27 blockchain tools:
Transaction Tools
minima_send_transaction- Send Minima or tokensminima_search_transactions- Search transaction historyminima_get_balance- Get wallet balanceminima_get_address- Generate new address
Token Tools
minima_create_token- Create new tokensminima_list_tokens- List all tokensminima_validate_token- Validate token ID
Smart Contract Tools
minima_execute_script- Execute Minima scriptsminima_validate_script- Validate script syntaxminima_generate_script- Generate from templatesminima_get_script_templates- Get available templates
AI-Powered Tools
minima_ai_explain_script- Explain script functionalityminima_ai_security_audit- Security analysisminima_ai_optimize_distribution- Optimize token distribution
P2P Communication (Maxima)
minima_maxima_send_message- Send P2P messagesminima_maxima_get_contacts- Get contact list
Analytics & Monitoring
minima_analytics_network- Network metricsminima_analytics_transactions- Transaction patternsminima_node_health- Node health statusminima_chain_info- Blockchain informationminima_mempool_info- Mempool status
Vault Operations
minima_vault_lock- Lock funds with time-lockminima_vault_status- Check vault status
Network Tools
minima_get_status- Full node statusminima_get_block- Get block by number/hashminima_get_peers- Get peer list
Backup
minima_backup_create- Create node backup
MCP Client Integration
Claude Desktop
To integrate with Claude Desktop:
-
Build the project:
npm run build -
Edit Claude Desktop configuration:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json -
Add this configuration:
{ "mcpServers": { "minima-blockchain": { "command": "node", "args": ["/absolute/path/to/minima-mcp/dist/index.js"], "env": { "MINIMA_HOST": "localhost", "MINIMA_PORT": "9005", "GOOGLE_API_KEY": "your_google_api_key" } } } } -
Restart Claude Desktop
See MCP_INTEGRATION.md for detailed instructions.
Autonomous Agent Examples
The examples/agents/ directory contains three production-ready autonomous agents:
1. Context Assistant
AI-powered assistant that answers questions using blockchain data:
npm run agent:assistant
2. Transaction Scheduler
Schedule recurring transactions (DCA, payments, distributions):
npm run agent:scheduler
3. Wallet Orchestrator
Optimize wallet operations and manage multiple addresses:
npm run agent:orchestrator
See examples/agents/README.md for detailed documentation.
API Reference
Tool Call Example
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
const transport = new StdioClientTransport({
command: 'node',
args: ['dist/index.js']
});
const client = new Client({
name: 'my-app',
version: '1.0.0'
}, {
capabilities: {}
});
await client.connect(transport);
// Get balance
const result = await client.callTool({
name: 'minima_get_balance',
arguments: {}
});
console.log(result);
Development
Building
npm run build
Development Mode
npm run dev
Testing
# All tests
npm test
# Unit tests only
npm run test:unit
# Integration tests
npm run test:integration
# Watch mode
npm run test:watch
Linting and Formatting
npm run lint
npm run format
Architecture
βββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Client (LLMs, Applications) β
β - Connects via stdio β
β - Calls blockchain tools β
βββββββββββββββ¬ββββββββββββββββββββββββββββββββ
β stdio
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Server (this project) β
β ββ Authentication & Authorization β
β ββ Tool Registry (27 tools) β
β ββ Prompt & Resource Registries β
β ββ Request Handlers β
βββββββββββββββ¬ββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββ
β Security Middleware β
β ββ Rate Limiter β
β ββ Transaction Limits β
β ββ Audit Logger β
β ββ Input Validation β
βββββββββββββββ¬ββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββ
β Services Layer β
β ββ Transaction, Token, Analytics β
β ββ Maxima, Vault, Script β
β ββ Node, AI Services β
β ββ Omnia (Layer 2) β
βββββββ¬ββββββββββββββββββββββββ¬ββββββββββββββββ
β β
β βΌ
β βββββββββββββββββββββββββββββ
β β AI Inference Gateway β
β β ββ Inference Router β
β β ββ Inference Client β
β β ββ Multi-model support β
β βββββββββ¬ββββββββββββββββββββ
β β HTTPS
β βΌ
β βββββββββββββββββββββββββββββ
β β AI Endpoints β
β β ββ Gemini 3 Pro β
β β ββ Claude Sonnet 4.5 β
β β ββ GPT-5 β
β β ββ Custom LLMs β
β β ββ Time-series models β
β βββββββββββββββββββββββββββββ
β
β Raw TCP (HTTP)
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββ
β Minima HTTP Client β
β ββ Raw TCP implementation β
β ββ Command execution β
β ββ Error handling β
βββββββββββββββ¬ββββββββββββββββββββββββββββββββ
β HTTP/RPC
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββ
β Minima Node (Port 9005) β
β ββ Blockchain operations β
β ββ Private key storage β
β ββ Transaction signing β
β ββ P2P networking β
βββββββββββββββββββββββββββββββββββββββββββββββ
Multi-Model Inference Support
The MCP server includes an inference gateway that supports multiple AI providers:
Supported Providers:
- Google Gemini (3 Pro)
- Anthropic Claude (Sonnet 4.5)
- OpenAI (GPT-5)
- Custom inference endpoints (local models, specialized models)
- Time-series forecasting models
Routing Strategies:
- Cost-based: Select cheapest endpoint
- Speed-based: Select fastest endpoint
- Quality-based: Select best model for task
See MULTI_MODEL_ARCHITECTURE.md for detailed implementation guide.
Security
Private Key Management
Private keys never leave the Minima node. The MCP server communicates with the node via RPC, and keys remain secure within the node's vault.
Transaction Limits
Configurable limits prevent unauthorized or excessive transactions:
- Per-transaction maximum
- Daily spending limits
- Approval thresholds for large transactions
- Maximum pending transactions
Audit Logging
All operations are logged in JSONL format for compliance and security auditing.
Rate Limiting
Prevents abuse with configurable rate limits per client.
Monitoring
Prometheus Metrics
Available at http://localhost:9090/metrics:
- Active connections
- Request rates
- Error rates
- Blockchain metrics (height, peers, etc.)
- Tool usage statistics
Grafana Dashboards
Access at http://localhost:3001 (when using Docker):
- Real-time blockchain metrics
- Transaction monitoring
- Error tracking
- Performance analytics
Troubleshooting
MCP Server won't start
Check Minima node is running:
curl http://localhost:9005/status
Verify environment variables:
cat .env
Check logs:
tail -f logs/app.log
Connection errors
Ensure correct port (9005 for RPC):
The Minima node must be started with -rpcenable flag:
java -jar minima.jar -rpcenable
Verify connectivity:
npm run health
AI features not working
AI features require GOOGLE_API_KEY to be set. Without it, the server returns fallback responses.
Project Structure
minima-mcp/
βββ src/
β βββ index.ts # Entry point
β βββ server.ts # MCP server implementation
β βββ minima/ # Minima client
β β βββ client.ts
β β βββ http-client.ts
β β βββ raw-http-client.ts
β β βββ types.ts
β βββ tools/ # MCP tool implementations
β β βββ registry.ts
β βββ services/ # Business logic
β β βββ transaction.service.ts
β β βββ token.service.ts
β β βββ analytics.service.ts
β β βββ ...
β βββ security/ # Security components
β βββ auth/ # Authentication
β βββ utils/ # Utilities
βββ examples/
β βββ agents/ # Autonomous agent examples
βββ tests/ # Test suites
βββ docker-compose.yml # Docker configuration
βββ package.json
Contributing
Contributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
Code Standards
- TypeScript strict mode
- ESLint compliance
- Comprehensive error handling
- Security-first approach
License
MIT License - see LICENSE file for details.
Copyright (c) 2025 Hilal Agil
Resources
- Minima Website: https://minima.global
- Minima Documentation: https://docs.minima.global
- MCP Protocol: https://modelcontextprotocol.io
- GitHub Repository: https://github.com/furcateresearch/minima-mcp
Acknowledgments
This project builds upon:
- Minima blockchain platform by Minima Global
- Model Context Protocol specification by Anthropic
- Google Gemini AI platform
