Vitruveo MCP Server (vtru-mcp)

A Model Context Protocol (MCP) server that provides read-only blockchain services for the Vitruveo network.

Vitruveo enhancement:
Added get_core_contracts, which returns a list of core Vitruveo contract addresses (treasury, system contracts, etc.).
More Vitruveo-specific tools will be added over time.

Forked from: mcpdotdirect/evm-mcp-server

📋 Contents

• Overview
• Features
• Vitruveo Tools
• Supported Network
• Prerequisites
• Installation
• Server Configuration
• Usage
• Connecting from MCP Clients
• API Reference
• Project Structure
• Development
• License

🔭 Overview

vtru-mcp exposes Vitruveo chain data to AI agents via the Model Context Protocol.

It is designed to be:

• Vitruveo-focused – chain ID 1490 only.
• Read-only – no private keys or signing.
• MCP-native – exposes tools + resources.
• Dual-transport – STDIO and HTTP/SSE.

✨ Features

Blockchain Data

• Latest block retrieval
• Get block by number
• Transaction lookup
• Transaction receipts
• Native VTRU balance
• Contract view/pure calls
• Token/NFT metadata (read-only)

Vitruveo-Specific

• get_core_contracts — returns Vitruveo system contract addresses.

Safe for Public Use

• No private keys
• No transfers or approvals
• No write methods

🌐 Supported Network

• Vitruveo Mainnet
  • Chain ID: 1490
  • RPC: https://rpc.vitruveo.xyz
  • Explorer: https://explorer.vitruveo.net

🛠️ Prerequisites

• Bun 1.0+
• Node 18+

📦 Installation

npm install -g @vitruveo/vtru-mcp

Or:

npx @vitruveo/vtru-mcp

From source:

git clone https://github.com/vitruveo/vtru-mcp.git
cd vtru-mcp
bun install

⚙️ Server Configuration

Defaults:

• Chain ID: 1490
• RPC: https://rpc.vitruveo.xyz
• Host: 0.0.0.0
• Port: 3001

🚀 Usage

STDIO (default)

npx @vitruveo/vtru-mcp

HTTP + SSE

npx @vitruveo/vtru-mcp --http

Endpoints:

• SSE: /sse
• Messages: /messages

🤖 Connecting from MCP Clients

Cursor (command mode)

.cursor/mcp.json:

{
  "mcpServers": {
    "vtru-mcp": {
      "command": "npx",
      "args": ["@vitruveo/vtru-mcp"]
    }
  }
}

Cursor (HTTP mode)

{
  "mcpServers": {
    "vtru-mcp-http": {
      "url": "http://localhost:3001/sse"
    }
  }
}

ChatGPT Desktop

• Type: Command
• Command: npx
• Args: @vitruveo/vtru-mcp

Claude CLI

claude mcp add vtru-mcp npx @vitruveo/vtru-mcp
claude

📚 API Reference

Tools

| Tool Name | Description | |---------------------|-------------------------------------------------| | get_core_contracts| Returns Vitruveo system contract addresses | | get_chain_info | Chain metadata (chainId, block, rpc) | | get_block | Fetch block by number or latest | | get_transaction | Transaction details | | get_balance | Native VTRU balance | | is_contract | Detect if address is a contract | | read_contract | View/pure call to a contract |

Token/NFT (read-only):

| Tool | Description | |---------------------|-----------------------------| | get-token-info | ERC20-style metadata | | get-token-balance | ERC20-style balance | | get-nft-info | NFT metadata | | get-nft-balance | NFT balance |

📁 Project Structure

vtru-mcp/
├── src/
│   ├── index.ts
│   ├── server/http-server.ts
│   ├── core/
│   │   ├── chains.ts
│   │   ├── tools.ts
│   │   ├── resources.ts
│   │   └── services/
│   │       ├── balance.ts
│   │       ├── blocks.ts
│   │       ├── transactions.ts
│   │       ├── contracts.ts
│   │       ├── tokens.ts
│   │       └── clients.ts
├── bin/cli.js
├── build/
└── package.json

🛠️ Development

bun dev
bun dev:http
bun run build
bun run build:http

Publishing:

npm run release

📄 License

MIT License — see LICENSE.