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 -clean flag 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 tokens
• minima_search_transactions - Search transaction history
• minima_get_balance - Get wallet balance
• minima_get_address - Generate new address

Token Tools

• minima_create_token - Create new tokens
• minima_list_tokens - List all tokens
• minima_validate_token - Validate token ID

Smart Contract Tools

• minima_execute_script - Execute Minima scripts
• minima_validate_script - Validate script syntax
• minima_generate_script - Generate from templates
• minima_get_script_templates - Get available templates

AI-Powered Tools

• minima_ai_explain_script - Explain script functionality
• minima_ai_security_audit - Security analysis
• minima_ai_optimize_distribution - Optimize token distribution

P2P Communication (Maxima)

• minima_maxima_send_message - Send P2P messages
• minima_maxima_get_contacts - Get contact list

Analytics & Monitoring

• minima_analytics_network - Network metrics
• minima_analytics_transactions - Transaction patterns
• minima_node_health - Node health status
• minima_chain_info - Blockchain information
• minima_mempool_info - Mempool status

Vault Operations

• minima_vault_lock - Lock funds with time-lock
• minima_vault_status - Check vault status

Network Tools

• minima_get_status - Full node status
• minima_get_block - Get block by number/hash
• minima_get_peers - Get peer list

Backup

• minima_backup_create - Create node backup

MCP Client Integration

Claude Desktop

To integrate with Claude Desktop:

1. Build the project:

   npm run build
   

2. Edit Claude Desktop configuration:

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   Windows: %APPDATA%\Claude\claude_desktop_config.json

3. 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"
         }
       }
     }
   }
   

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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. 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