Skip to main content
Glama
VeChain MCP Server

VeChain MCP Server

Official
by vechain

VeChain MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to VeChain ecosystem documentation and blockchain data. This server enables seamless integration of VeChain capabilities into AI workflows through the MCP standard.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely access external data and tools. This server implements MCP to provide VeChain-specific capabilities to any MCP-compatible client.

Related MCP server: VeChain MCP Server

Features

  • Unified Documentation Search: Search across multiple VeChain ecosystem documentation resources

  • Blockchain Data Access: Query VeChain Thor blockchain data (blocks, transactions, accounts)

  • Event Decoding: Decode raw blockchain events into human-readable format

  • Multi-Network Support: Connect to mainnet, testnet, or solo networks

Supported Documentation Sources

  1. VeChain Documentation - Core VeChain blockchain documentation

  2. VeChain Kit - VeChain development toolkit documentation

  3. VeBetterDao - Decentralized governance platform documentation

  4. VeVote - Voting platform documentation

  5. Stargate - VeChain infrastructure documentation

Prerequisites

  • Node.js 20.18.1 or higher (required for running the server)

  • An MCP-compatible client such as:

Available Tools

Documentation Search Tools

  • searchDocsVechain - Search VeChain documentation

  • searchDocsVechainKit - Search VeChain Kit documentation

  • searchDocsVebetterDao - Search VeBetterDao documentation

  • searchDocsVevote - Search VeVote documentation

  • searchDocsStargate - Search Stargate documentation

Thor Blockchain Tools

  • thorGetBlock - Get block information

  • thorGetTransaction - Get transaction details

  • thorGetAccount - Get account information

  • thorDecodeEvent - Decode raw blockchain events

Token & NFT Tools

  • getTokenBalances - Get token balances for an account

  • getTokenFiatPrice - Get fiat price for tokens

  • getTokenRegistry - Get token registry information

  • getNFTs - Get NFTs owned by an account

  • getNFTContracts - Get NFT contract information

B3TR & VeBetterDAO Tools

  • getB3TRGlobalOverview - Get B3TR global statistics

  • getB3TRAppsLeaderboard - Get leaderboard of B3TR apps

  • getB3TRProposalsResults - Get B3TR proposal voting results

  • getB3TRProposalComments - Get on-chain voting comments

  • getCurrentRound - Get current VeBetterDAO round info

  • getGMNFTStatus - Check GM NFT status for an account

Stargate Staking Tools

  • getStargateTotalVetStaked - Get total VET staked

  • getStargateTokenRewards - Get staking rewards

  • getValidators - Get validator information

Transaction & Transfer Tools

  • getTransactions - Get transactions for an account

  • getTransfersOfAccount - Get token transfers

  • getHistoryOfAccount - Get account history

...and many more! Use the MCP inspector or ask your AI assistant to list all available tools.

Quick Start

1. Install in Your MCP Client

The easiest way to use the VeChain MCP server is to install it directly from npm using npx. This method automatically downloads and runs the latest version without requiring local setup.

For Claude Desktop

  1. Locate your Claude Desktop configuration file:

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

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    • Linux: ~/.config/Claude/claude_desktop_config.json

  2. Add the VeChain server configuration:

{
  "mcpServers": {
    "vechain": {
      "command": "npx",
      "args": ["-y", "@vechain/mcp-server@latest"],
      "env": {
        "VECHAIN_NETWORK": "mainnet"
      }
    }
  }
}
  1. Restart Claude Desktop

For Cursor

  1. Open Cursor Settings:

    • Press Cmd/Ctrl + Shift + P

    • Type "Open MCP Settings" and select it

  2. Add the VeChain server configuration (same JSON as above)

  3. Restart Cursor

For Claude Code

  1. Locate your Claude Code configuration file:

    • Create or edit ~/.claude/mcp.json

  2. Add the VeChain server configuration (same JSON as above)

  3. Restart Claude Code

2. Verify Installation

Once your MCP client restarts, you should see the VeChain MCP tools available. You can test by asking your AI assistant:

  • "Search VeChain documentation for VTHO"

  • "Get the latest block on VeChain"

  • "What is my VeChain account balance for address 0x..."

Configuration

Network Selection

Set the VECHAIN_NETWORK environment variable to connect to different VeChain networks:

  • mainnet - VeChain MainNet (default, production network)

  • testnet - VeChain TestNet (for testing and development)

  • solo - Local solo network (for local development)

Example configuration for testnet:

{
  "mcpServers": {
    "vechain": {
      "command": "npx",
      "args": ["-y", "@vechain/mcp-server"],
      "env": {
        "VECHAIN_NETWORK": "testnet"
      }
    }
  }
}

Run with Docker

Prerequisite: Docker 20+.

  1. Pull the multi‑arch image (amd64/arm64):

docker pull ghcr.io/vechain/vechain-mcp-server:latest
  1. Run the HTTP server:

docker run -d --rm \
  -p 4000:4000 \
  -e VECHAIN_NETWORK=mainnet \ # mainnet | testnet | solo
  -e MCP_API_KEY=replace-me \  # bearer token clients must send on /mcp
  --name vechain-mcp \
  ghcr.io/vechain/vechain-mcp-server:latest

For local experimentation you can set MCP_AUTH_DISABLED=true instead of MCP_API_KEY; the server then accepts unauthenticated requests on /mcp. The server refuses to start with this flag when NODE_ENV=production.

  1. Verify:

curl -fsS http://localhost:4000/health
  1. List MCP tools (optional check):

curl -sS -m 10 -X POST http://localhost:4000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer replace-me' \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}'

Notes:

  • MCP endpoint: POST /mcp (Content-Type: application/json, Accept: application/json, text/event-stream).

  • Auth: POST /mcp, GET /tools and POST /tools/call require Authorization: Bearer <MCP_API_KEY>. GET /health and GET /ready are unauthenticated so a load balancer can probe them.

Local Development Setup

If you want to contribute to the VeChain MCP server or test local changes, follow these instructions.

Prerequisites for Development

  • Node.js 20.18.1 or higher

  • npm or yarn package manager

  • Git

Setup Steps

  1. Clone the repository:

git clone https://github.com/vechain/vechain-mcp-server.git
cd vechain-mcp-server
  1. Install dependencies:

npm install
  1. Build the project:

npm run build

Development Modes

Option 1: STDIO Mode (Production-like)

Use this mode to test the server as it would run in production (via stdin/stdout).

  1. Build the project (if not already done):

npm run build
  1. Configure your MCP client to use the local build:

{
  "mcpServers": {
    "vechain-local": {
      "command": "node",
      "args": ["/absolute/path/to/vechain-mcp-server/dist/stdio.js"],
      "env": {
        "VECHAIN_NETWORK": "testnet"
      }
    }
  }
}

Replace /absolute/path/to/vechain-mcp-server with the actual path to your cloned repository.

  1. Restart your MCP client

Note: For Claude Code and Cursor, the local configuration is already set up in .claude/mcp.json and .cursor/mcp.json respectively.

Option 2: HTTP Mode with Hot Reload (Active Development)

Use this mode when actively developing - it automatically reloads on file changes.

  1. Start the development server:

npm run dev

This starts an HTTP server on http://localhost:4000/mcp with file watching enabled.

  1. Configure your MCP client to connect via HTTP:

{
  "mcpServers": {
    "vechain-local-dev": {
      "url": "http://localhost:4000/mcp"
    }
  }
}
  1. Restart your MCP client

Now any changes you make to the source code will automatically reload the server.

Note: This HTTP mode currently works with Cursor and other clients that support HTTP transport. Claude Desktop may have limited support for HTTP-based MCP servers.

Testing Your Changes

Using MCP Inspector

The MCP Inspector provides a web UI to test your MCP tools interactively:

npm run inspect

This opens a browser interface where you can test individual tools and see their responses.

Discourse Forum Integration (Optional)

Forum tools are OPTIONAL and work without the Discourse MCP server by providing forum URLs for manual viewing. To enable automated forum data fetching:

# Install globally
npm install -g @discourse/mcp@latest

# Run in HTTP transport mode with site pre-configured (recommended)
npx -y @discourse/mcp@latest --transport http --site https://vechain.discourse.group

# Or if installed globally
discourse-mcp --transport http --site https://vechain.discourse.group

Important: The --transport http flag is required to run Discourse MCP as an HTTP server that the VeBetterDAO MCP can connect to as an upstream server. Without this flag, it will run in STDIO mode (designed for direct AI client integration like Claude Desktop).

The Discourse server runs on http://localhost:3000 by default. The VeChain MCP will automatically connect to it if running.

Without Discourse MCP:

  • Forum tools will provide direct URLs to view discussions manually

  • Example: https://vechain.discourse.group/t/proposal-name/559

With Discourse MCP (HTTP mode):

  • Forum tools will fetch full discussion content automatically

  • Analyze sentiment and extract key points programmatically

Quick Start Commands:

# Terminal 1: Start Discourse MCP (with site pre-configured)
npx -y @discourse/mcp@latest --transport http --site https://vechain.discourse.group

# Terminal 2: Start VeBetterDAO MCP
npm run dev

Running Automated Tests

  1. Build and start the server:

npm run build
npm run start
  1. In a separate terminal, run the test suite:

npm run test

Code Quality

Format and lint your code before committing:

npm run format  # Format code with Biome
npm run lint    # Lint and fix issues with Biome

Releases

Releases are driven by git tags. Pushing a tag triggers a single pipeline (.github/workflows/publish-release.yml) that:

  1. Publishes the npm package to npmjs.org and to GitHub Packages.

  2. Builds a multi-arch Docker image and pushes it to the dev and prod container registries.

  3. Rolls the new image out to the dev environment automatically.

  4. Pauses on a manual approval step before rolling out to prod (enforced by GitHub environment protection rules).

Infrastructure for the runtime service lives in infra/ as a CloudFormation template; see that directory's README for details on how to deploy or update the stack shape.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Available Tools

76 tools
buildContractTransactionBuild a multi-clause transaction ready for the wallet to signA
DestructiveIdempotent

Build (but never sign or broadcast) a multi-clause VeChainThor transaction. Each clause is { name, method, args, valueWei?, comment?, address? }; for erc20 / erc721 an explicit address is mandatory. Returns the array of { to, value, data, comment? } clauses ready to be passed to VeWorld, the dApp Kit or vechain-kit for signing. By default every clause is simulated via Thor multicall first (using a generic signer): reverts are surfaced in simulation.results so the agent can fix the request before asking the user to sign. The server NEVER holds private keys and NEVER broadcasts.

Inputs: clauses (required), simulate. Returns: ok, data, error, network

callContractRead state from one or many contracts via a single multicallA
Read-onlyIdempotent

Execute one or more read-only contract calls (view / pure methods) in a single multicall round-trip. Each clause is { name, method, args, address? } where name is a registry contract from listKnownContracts. Pass address only to override the registry default or when calling erc20 / erc721 on an arbitrary token. Returns one result per clause with success, the decoded primary value and the full decoded array. bigint values are stringified. Use this instead of one call per round-trip whenever you need multiple values.

Inputs: clauses (required). Returns: ok, data, error, network

getAccountsTotalsAccounts: totals/time-seriesA
Read-onlyIdempotent

Retrieve total unique VeChain accounts by timeframe via /api/v1/accounts/totals. Provide timeFrame (DAY, WEEK, MONTH, YEAR) to get per-interval totals; omit timeFrame to get cumulative ALL. Supports pagination.

Inputs: page, size, cursor, direction, +1 more. Returns: ok, data, error, network

getAppHubAppsApp Hub: official apps on VeChainA
Read-onlyIdempotent

List official apps from VeChain App Hub. Supports filtering by category, tag, VeWorld support and free-text search. Always return app URL when available.

Inputs: tag, query, category, isVeWorldSupported. Returns: ok, data, error, network

getB3TRActionsForAppB3TR: Actions for an appA
Read-onlyIdempotent

Fetch B3TR actions for a VeBetterDAO app via /api/v1/b3tr/actions/apps/{appId}. Requires appId (if coming from app-hub from name or description, use veBetterDaoId).

Inputs: appId (required), page, size, after, +2 more. Returns: ok, data, error, network

getB3TRActionsForUserB3TR: Actions for a userA
Read-onlyIdempotent

Get B3TR actions for a user and the impacts of those actions via /api/v1/b3tr/actions/users/{wallet}. Optionally filter by appId and time range.

Inputs: wallet (required), page, size, after, +3 more. Returns: ok, data, error, network

getB3TRAppOverviewB3TR: App overview (totals)A
Read-onlyIdempotent

Get APP overview for a specific app listed on veBetterDao via /api/v1/b3tr/actions/apps/{appId}/overview. Returns total B3TR rewards, number of rewarded actions, sustainability impact totals, global rankings for a specific app. appId must be the veBetterDaoId (32-byte hex, e.g. 0x2fc30c...). If the user gives an app name like "Mugshot", call getAppHubApps first to resolve the veBetterDaoId — never pass an app name directly here. Optionally filter by roundId OR date (yyyy-MM-dd UTC), but not both — they are mutually exclusive.

Inputs: appId (required), date, roundId. Returns: ok, data, error, network

getB3TRAppsLeaderboardB3TR: Apps leaderboardA
Read-onlyIdempotent

Get app B3TR action leaderboard via /api/v1/b3tr/actions/leaderboards/apps. Optionally filter by roundId OR date (yyyy-MM-dd UTC) but not both — they are mutually exclusive. Sort by totalRewardAmount or actionsRewarded; supports cursor pagination.

Inputs: date, size, cursor, sortBy, +2 more. Returns: ok, data, error, network

getB3TRAppUsersLeaderboardB3TR: App users leaderboardA
Read-onlyIdempotent

Get user B3TR action leaderboard for a given app via /api/v1/b3tr/actions/leaderboards/apps/{appId}. Optionally filter by roundId or date; sort by totalRewardAmount or actionsRewarded; supports cursor pagination.

Inputs: appId (required), date, size, cursor, +3 more. Returns: ok, data, error, network

getB3TRGlobalOverviewB3TR: Global overview (totals)A
Read-onlyIdempotent

Get global B3TR action overview via /api/v1/b3tr/actions/global/overview. Optionally filter by roundId OR date (yyyy-MM-dd UTC), but not both — they are mutually exclusive.

Inputs: date, roundId. Returns: ok, data, error, network

getB3TRProposalCommentsB3TR: Proposal commentsA
Read-onlyIdempotent

Get on-chain voting comments/reasons for a specific B3TR proposal via /api/v1/b3tr/proposals/{proposalId}/comments. Shows comments from users who actually voted on-chain with their voting power and weight. NOTE: This shows on-chain voter comments. For broader community discussion, extract the Discourse forum link from the proposal's IPFS description. If getDiscourseTopic is available, use it to fetch the full forum thread; if not available (optional feature), provide the forum URL for manual viewing. Forum discussions often have more detailed debate and sentiment from the wider community before/during voting. Supports filtering by support type (FOR, AGAINST, ABSTAIN).

Inputs: proposalId (required), page, size, support, +1 more. Returns: ok, data, error, network

getB3TRProposalsResultsB3TR: Proposal resultsA
Read-onlyIdempotent

Get B3TR proposal results via /api/v2/b3tr/proposals/results. IMPORTANT: If user provides a specific proposal ID, pass it as the proposalId parameter to query directly for that single proposal - DO NOT fetch all proposals and filter! Returns proposals with voting results and IPFS description CIDs. WORKFLOW: 1) Use this tool with proposalId parameter if specific proposal requested, or browse all proposals if general query, 2) Use getIPFSContent with the description CID to get full proposal details, 3) Extract Discourse forum link from description (format: vechain.discourse.group/t/topic-name/TOPIC_ID), 4) If getDiscourseTopic is available, use it with the topic ID to fetch community discussion; if not available (optional feature), provide the forum URL for manual viewing, 5) Use getB3TRProposalComments to get on-chain voting comments. This gives complete view: proposal data + forum discussion (via API or URL) + on-chain voter comments.

Inputs: page, size, states, direction, +1 more. Returns: ok, data, error, network

getB3TRUserAppOverviewB3TR: User app overview (totals)A
Read-onlyIdempotent

Get a users overview for a specific app on veBetterDao via /api/v1/b3tr/actions/users/{wallet}/app/{appId}/overview. Returns total B3TR rewards, number of rewarded actions, sustainability impact totals, global rankings for a specific app. appId must be the veBetterDaoId (32-byte hex). If the user gives an app name, call getAppHubApps first to resolve the veBetterDaoId. Optionally filter by roundId OR date (yyyy-MM-dd UTC), but not both — they are mutually exclusive.

Inputs: appId (required), wallet (required), date, roundId. Returns: ok, data, error, network

getB3TRUserDailySummariesB3TR: User daily summariesA
Read-onlyIdempotent

Get daily action summaries for a specific user within a date range via /api/v1/b3tr/actions/users/{wallet}/daily-summaries. Returns total B3TR rewards, number of rewarded actions, sustainability impact totals for each day. Dates must be UTC in yyyy-MM-dd.

Inputs: wallet (required), endDate (required), startDate (required), page, +2 more. Returns: ok, data, error, network

getB3TRUserOverviewB3TR: User overview (totals)A
Read-onlyIdempotent

Get the B3TR action overview for a specific wallet via /api/v1/b3tr/actions/users/{wallet}/overview. Returns total B3TR rewards, number of rewarded actions, sustainability impact totals, global rankings, and unique X-App interactions. Optionally filter by roundId OR date (yyyy-MM-dd UTC), but not both — they are mutually exclusive.

Inputs: wallet (required), date, roundId. Returns: ok, data, error, network

getB3TRUsersLeaderboardB3TR: Users leaderboardA
Read-onlyIdempotent

Get leaderboard of users' B3TR actions via /api/v1/b3tr/actions/leaderboards/users. Optionally filter by roundId OR date (yyyy-MM-dd UTC) but not both — they are mutually exclusive. Sort by totalRewardAmount or actionsRewarded; supports cursor pagination.

Inputs: date, size, cursor, sortBy, +2 more. Returns: ok, data, error, network

getContractAbiGet the ABI (or a subset) of a known contractA
Read-onlyIdempotent

Return the ABI of a contract registered in the server, with optional filters to keep the payload small. Always prefer the most specific filters: pass methodNames: ["balanceOf", "transfer"] to get just those fragments, or stateMutability: "view" to list read-only methods. When called with no filters on a large ABI the server returns only the list of function names and asks you to refine the query (the full ABI would be tens of KB). Use the returned fragments directly in callContract / buildContractTransaction together with the same name.

Inputs: name (required), methodNames, fragmentType, stateMutability. Returns: ok, data, error, network

getContractTransactionsIndexer: Transactions for a contract (v1)A
Read-only

Query VeWorld Indexer /api/v1/transactions/contract for transactions interacting with a contract address. Supports pagination.

Inputs: contractAddress (required), page, size, after, +4 more. Returns: ok, data, error, network

getCurrentRoundVeBetterDAO: Get current round IDA
Read-onlyIdempotent

Get the current VeBetterDAO round ID by querying the X Allocation Voting smart contract directly. Rounds are time periods for voting cycles and reward distribution. Use this round ID to filter other queries (e.g., getB3TRGlobalOverview, getB3TRAppOverview) to see data for the current active round. Returns real-time on-chain value.

Inputs: no named parameters. Returns: ok, error, network, currentRoundId

getDelegatedTransactionsIndexer: Delegated transactions by delegator (v1)A
Read-only

Query VeWorld Indexer /api/v1/transactions/delegated for transactions delegated by a given delegator address. Supports pagination.

Inputs: delegator (required), page, size, after, +4 more. Returns: ok, data, error, network

getDiscourseCategoriesGet Forum Categories (Optional)A
Read-onlyIdempotent

Get all available categories from the VeBetterDAO Discourse forum. OPTIONAL FEATURE: Requires Discourse MCP server running separately. If not available, suggest visiting https://vechain.discourse.group/categories to browse categories.

Inputs: no named parameters.

getDiscourseLatestTopicsGet Latest Forum Topics (Optional)A
Read-onlyIdempotent

Get the latest topics from the VeBetterDAO Discourse forum. Returns standard page size by default. OPTIONAL FEATURE: Requires Discourse MCP server running separately. If not available, suggest visiting https://vechain.discourse.group directly. Useful for browsing what the community is currently discussing, finding new proposal discussions, or monitoring general sentiment.

Inputs: page, category, per_page.

getDiscoursePostGet Forum Post (Optional)A
Read-onlyIdempotent

Get a specific post from the VeBetterDAO Discourse forum by post ID. Useful for reading specific replies or comments in detail. OPTIONAL FEATURE: Requires Discourse MCP server running separately.

Inputs: postId (required).

getDiscourseTopicGet Forum Topic (Optional)A
Read-onlyIdempotent

Get detailed information about a specific Discourse forum topic, including posts and replies. Returns 5 posts by default. OPTIONAL FEATURE: Requires Discourse MCP server running separately. CRITICAL FOR B3TR PROPOSALS: Proposal descriptions (fetched via getIPFSContent) often contain Discourse forum links in the format vechain.discourse.group/t/topic-name/TOPIC_ID. If this tool is not available, provide the direct forum URL for manual viewing. Example: from URL "https://vechain.discourse.group/t/vebetterdao-proposal-auto-voting/559" extract topicId: 559.

Inputs: topicId (required), post_limit.

getExplorerBlockUsageBlock usage statisticsA
Read-onlyIdempotent

Get cumulative block usage statistics (gas, tx counts, clauses, base fee) over a timestamp range via /api/v1/explorer/block-usage. Query: startTimestamp, endTimestamp (Unix seconds, inclusive). Returns cumulative counters at sampled points; compute deltas client-side.

Inputs: endTimestamp (required), startTimestamp (required). Returns: ok, data, error, network

getFungibleTokenContractsIndexer: List wallet fungible tokens (VIP-180/ERC‑20‑like)A
Read-only

List fungible token contract addresses for a wallet via Indexer. Use with getTokenRegistry for metadata. Endpoint: /api/v1/transfers/fungible-tokens-contracts.

Inputs: address (required), page, size, cursor, +2 more. Returns: ok, data, error, network

getGMNFTStatusVeBetterDAO: Get Galaxy Member NFT statusA
Read-onlyIdempotent

Check if a wallet address owns a Galaxy Member (GM) NFT and get its details. Uses hybrid approach: 1) Indexer to quickly check IF user has GM NFT (cached, fast), 2) Smart contract to get precise level/tier details. Galaxy Member NFTs provide special governance rights and benefits in VeBetterDAO. Returns whether the address holds a GM NFT, token ID(s), and level/tier.

Inputs: address (required). Returns: ok, error, gmNFT, address, +1 more

getHistoryOfAccountGet History of accountA
Read-only

Retrieve transaction history for a VeChain address with filtering support.

IMPORTANT: Pass ARRAYS of event names to fetch multiple event types in ONE call - this is much more efficient than separate calls.

Available Event Types:

STARGATE STAKING (Current - Post-Hayabusa):

  • STARGATE_STAKE: User stakes VET and mints Stargate NFT

  • STARGATE_UNSTAKE: User unstakes VET and burns NFT

  • STARGATE_DELEGATE_REQUEST: User requests to delegate NFT to validator

  • STARGATE_DELEGATE_ACTIVE: Delegation becomes active with validator

  • STARGATE_DELEGATE_EXIT_REQUEST: User requests to exit delegation

  • STARGATE_DELEGATION_EXITED: Delegation fully exited, can unstake

  • STARGATE_DELEGATION_EXITED_VALIDATOR: Validator-side exit event

  • STARGATE_DELEGATE_REQUEST_CANCELLED: Delegation request cancelled before activation

  • STARGATE_CLAIM_REWARDS: User claims VTHO staking rewards

  • STARGATE_BOOST: User boosts NFT maturity with VTHO payment

  • STARGATE_MANAGER_ADDED: User adds manager address to control NFT

  • STARGATE_MANAGER_REMOVED: Manager address removed from NFT

STARGATE LEGACY (Pre-Hayabusa - Historical only):

  • STARGATE_DELEGATE_LEGACY: Old delegation system

  • STARGATE_CLAIM_REWARDS_BASE_LEGACY: Old base rewards

  • STARGATE_CLAIM_REWARDS_DELEGATE_LEGACY: Old delegation rewards

  • STARGATE_UNDELEGATE_LEGACY: Old undelegation

TRANSFERS:

  • TRANSFER_VET: Native VET token transfers

  • TRANSFER_FT: Fungible token (VIP-180) transfers - includes VTHO, other tokens

  • TRANSFER_NFT: NFT (VIP-181/VIP-721) transfers

  • TRANSFER_SF: Semi-fungible token transfers

SWAPS (DEX Activity):

  • SWAP_VET_TO_FT: Swapping VET for tokens

  • SWAP_FT_TO_VET: Swapping tokens for VET

  • SWAP_FT_TO_FT: Token-to-token swaps

VEBETTERDAO (B3TR Ecosystem):

  • B3TR_SWAP_VOT3_TO_B3TR: Converting VOT3 governance token to B3TR

  • B3TR_SWAP_B3TR_TO_VOT3: Converting B3TR to VOT3

  • B3TR_PROPOSAL_SUPPORT: Supporting a proposal with B3TR

  • B3TR_PROPOSAL_VOTE: Voting on governance proposal

  • B3TR_PROPOSAL_WITHDRAW: Withdrawing a B3TR proposal

  • B3TR_XALLOCATION_VOTE: Voting on X-Allocation distribution

  • B3TR_CLAIM_REWARD: Claiming B3TR ecosystem rewards

  • B3TR_UPGRADE_GM: Upgrading governance model

  • B3TR_ACTION: General B3TR ecosystem action

GOVERNANCE:

  • VEVOTE_VOTE_CAST: Vote cast in VeVote governance system

OTHER:

  • NFT_SALE: NFT marketplace sale transaction

  • UNKNOWN_TX: Unclassified transaction type

Common Query Patterns:

Complete Stargate history: ["STARGATE_STAKE", "STARGATE_UNSTAKE", "STARGATE_DELEGATE_REQUEST", "STARGATE_DELEGATE_ACTIVE", "STARGATE_DELEGATE_EXIT_REQUEST", "STARGATE_DELEGATION_EXITED", "STARGATE_CLAIM_REWARDS", "STARGATE_BOOST", "STARGATE_MANAGER_ADDED", "STARGATE_MANAGER_REMOVED"]

All asset transfers: ["TRANSFER_VET", "TRANSFER_FT", "TRANSFER_NFT", "TRANSFER_SF"]

Trading activity: ["SWAP_VET_TO_FT", "SWAP_FT_TO_VET", "SWAP_FT_TO_FT"]

Filters:

  • eventName: Single string OR array (ALWAYS prefer arrays for related events)

  • searchBy: 'to' | 'from' | 'origin' | 'gasPayer' - filter by address role

  • contractAddress: Filter by specific contract interactions

  • after/before: Unix timestamps in SECONDS (NOT milliseconds). Example: 2025-08-03 00:00 UTC = 1754179200, 2025-08-04 00:00 UTC = 1754265600

  • Pagination: page, size, cursor, direction (ASC/DESC)

Returns paginated array of events with full transaction details.

Inputs: address (required), page, size, after, +6 more. Returns: ok, data, error, network

getIPFSContentIPFS: Fetch content by CIDA
Read-onlyIdempotent

Fetch content from IPFS using the VeChain gateway proxy (api.gateway-proxy.vechain.org). Provide an IPFS Content Identifier (CID) to retrieve the associated data. Commonly used to fetch B3TR proposal descriptions. IMPORTANT: Proposal descriptions often contain Discourse forum links (vechain.discourse.group/t/topic-name/TOPIC_ID or discourse.vebetterdao.org/t/topic-name/TOPIC_ID). After fetching IPFS content, search for these links and extract them. If getDiscourseTopic is available, use it with the topic ID. If not available (optional feature), provide the full forum URL for manual viewing to see community discussion and sentiment.

Inputs: cid (required). Returns: ok, cid, error, content

getNFTContractsIndexer: List NFT contract addresses by ownerA
Read-only

Get all NFT contract addresses for a given owner using VeWorld Indexer. Endpoint: /api/v1/nfts/contracts. Accepts address and pagination (page/size/direction or cursor).

Inputs: page, size, owner, cursor, +2 more. Returns: ok, data, error, network

getNFTsIndexer: List NFTs owned by an addressA
Read-only

Get all NFTs owned by an address using VeWorld Indexer. Endpoint: /api/v1/nfts. Accepts address, optional contractAddress, and pagination (page/size/direction or cursor).

Inputs: page, size, cursor, address, +2 more. Returns: ok, data, error, network

getStargateNftHoldersByPeriodIndexer: Stargate NFT holders by periodA
Read-onlyIdempotent

Time‑series of total Stargate NFT holders by period (DAY, WEEK, MONTH, YEAR, ALL). Each element corresponds to an interval at the selected granularity.

Inputs: period (required). Returns: ok, data, error, network

getStargateNftHoldersHistoricIndexer: Historic total NFT holdersA
Read-onlyIdempotent

Running-total time series of total NFT holders in Stargate, optionally filtered by NFT level. Endpoint: /api/v1/stargate/nft-holders/historic/{range}.

Inputs: range (required), level. Returns: ok, data, error, network

getStargateNftHoldersTotalIndexer: Total stargate NFT (total)A
Read-onlyIdempotent

Get the total number of Stargate NFTs and breakdown by level via /api/v1/stargate/nft-holders. Returns an object with block metadata, total, and byLevel.

Inputs: no named parameters. Returns: ok, data, error, network

getStargateTokenRewardsIndexer: Stargate token rewardsA
Read-onlyIdempotent

Overview of rewards earned by a Stargate NFT delegation to a validator over time. Not the same as “claimed” (claimable only at end of cycle). Supports periodType (CYCLE, DAY, WEEK, MONTH, YEAR, ALL), optional validator, and pagination.

Inputs: tokenId (required), periodType (required), page, size, +3 more. Returns: ok, data, error, network

getStargateTokensIndexer: Stargate tokensA
Read-onlyIdempotent

Fetch Stargate NFT information (VET staked, rewards, level, delegation status, validator id, etc.) via /api/v1/stargate/tokens. Supports filtering by owner, manager, or tokenId; supports pagination (page, size, direction).

Inputs: page, size, owner, cursor, +3 more. Returns: ok, data, error, network

getStargateTotalVetStakedIndexer: Total VET staked (with per-level breakdown)A
Read-onlyIdempotent

Get total VET staked in Stargate at latest or at a specific block via /api/v1/stargate/total-vet-staked. Returns block metadata, total, and byLevel breakdown.

Inputs: blockNumber. Returns: ok, data, error, network

getStargateTotalVetStakedHistoricIndexer: Historic total VET stakedA
Read-onlyIdempotent

Running-total time series of total VET staked in Stargate, optionally filtered by NFT level. Endpoint: /api/v1/stargate/total-vet-staked/historic/{range}.

Inputs: range (required), level. Returns: ok, data, error, network

getStargateTotalVthoClaimedIndexer: Stargate total VTHO claimedA
Read-onlyIdempotent

Fetch the total VTHO that Stargate users have actually claimed from rewards generated by delegations. Returns a numeric value encoded as a JSON string. Optional: blockNumber for historical snapshots; rewardsType can filter by LEGACY (pre‑Hayabusa) or DELEGATED (post‑Hayabusa).

Inputs: blockNumber, rewardsType. Returns: ok, data, error, network

getStargateTotalVthoClaimedByAccountStargate: Total VTHO claimed by accountA
Read-onlyIdempotent

Get total VTHO claimed by a given account via /api/v1/stargate/total-vtho-claimed/{account}. Optional rewardsType filter: LEGACY (pre‑Hayabusa bootstrap) or DELEGATION (post‑Hayabusa delegated) if not provided, all rewards ever claimed are included.

Inputs: account (required), rewardsType. Returns: ok, data, error, network

getStargateTotalVthoClaimedByAccountTokenStargate: Total VTHO claimed by account and tokenA
Read-onlyIdempotent

Get total VTHO claimed by a given account and token via /api/v1/stargate/total-vtho-claimed/{account}/{tokenId}. Optional rewardsType filter: LEGACY (pre‑Hayabusa bootstrap) or DELEGATION (post‑Hayabusa delegated).

Inputs: account (required), tokenId (required), rewardsType. Returns: ok, data, error, network

getStargateTotalVthoClaimedHistoricIndexer: Historic total VTHO claimedA
Read-onlyIdempotent

Running-total time series of total VTHO claimed across Stargate. Endpoint: /api/v1/stargate/total-vtho-claimed/historic/{range}.

Inputs: range (required). Returns: ok, data, error, network

getStargateTotalVthoGeneratedIndexer: Stargate total VTHO generatedA
Read-onlyIdempotent

Fetch the total VTHO generated by Stargate delegations from validators’ block rewards (aggregate produced, whether or not claimed). Returns a numeric value encoded as a JSON string. Optional: blockNumber for historical snapshots.

Inputs: blockNumber. Returns: ok, data, error, network

getStargateTotalVthoGeneratedHistoricIndexer: Historic total VTHO generatedA
Read-onlyIdempotent

Running-total time series of total VTHO generated across Stargate. Endpoint: /api/v1/stargate/total-vtho-generated/historic/{range}.

Inputs: range (required). Returns: ok, data, error, network

getStargateVetDelegatedByPeriodIndexer: Stargate VET delegated by periodA
Read-onlyIdempotent

Time‑series of VET delegated to validators via Stargate by period (DAY, WEEK, MONTH, YEAR, ALL). Useful for tracking delegation flows over time.

Inputs: period (required). Returns: ok, data, error, network

getStargateVetStakedByPeriodIndexer: Stargate VET staked by periodA
Read-onlyIdempotent

Time‑series of VET staked (locked via Stargate) by period (DAY, WEEK, MONTH, YEAR, ALL). Each element is the total amount staked during that interval.

Inputs: period (required). Returns: ok, data, error, network

getStargateVthoClaimedByPeriodIndexer: Stargate VTHO claimed by periodA
Read-onlyIdempotent

Time‑series of VTHO that users actually claimed from Stargate rewards by period (DAY, WEEK, MONTH, YEAR, ALL). Values represent the claimed subset of generated rewards per interval. Only take into account rewaerds that were claimed post hayabusa.

Inputs: period (required). Returns: ok, data, error, network

getStargateVthoGeneratedByPeriodIndexer: Stargate VTHO generated by periodA
Read-onlyIdempotent

Time‑series of VTHO generated from validators’ block rewards by period (DAY, WEEK, MONTH, YEAR, ALL). Each element represents the amount generated during that interval; use it to chart production over time.

Inputs: period (required). Returns: ok, data, error, network

getTokenBalancesGet Token BalanceA
Read-onlyIdempotent

Get the balance of any VIP-180/ERC-20 token for a wallet address by querying the smart contract directly. Returns the raw balance (smallest unit), formatted balance (human-readable), decimals, and token metadata (symbol, name) if available. Requires the token contract address.

Inputs: address (required), tokenAddress (required). Returns: ok, error, balance, network, +1 more

getTokenFiatPriceGet token price in fiat (VET/VTHO/B3TR)A
Read-onlyIdempotent

Get the current price of VET, VTHO, or B3TR in a given fiat currency using the on-chain VeChain Energy Oracle.

Inputs: fiat (required), token (required). Returns: fiat, error, price, token, +1 more

getTokenRegistryToken Registry: list known tokens (mainnet/testnet)A
Read-onlyIdempotent

Fetch the VeChain token registry curated list for the current network (VECHAIN_NETWORK=mainnet|testnet). Use this to identify official tokens, metadata (decimals, symbol, website), and bridge provenance. Supports optional filtering by symbol or contract address.

Inputs: symbol, address. Returns: ok, data, error, network

getTransactionByIdIndexer: Transaction by ID (v1)A
Read-onlyIdempotent

Get a single decoded transaction (with events) by ID from VeWorld Indexer. Endpoint: /api/v1/transactions/{txId}.

Inputs: txId (required), expanded. Returns: ok, data, error, network

getTransactionsIndexer: Transactions by origin or delegator (v1)A
Read-only

Query VeWorld Indexer /api/v1/transactions. Provide either 'origin' or 'delegator' address with optional time filters and pagination. Returns decoded events.

Inputs: page, size, after, before, +5 more. Returns: ok, data, error, network

getTransfersForBlockIndexer: Transfers for block (v1)A
Read-only

Query VeWorld Indexer /api/v1/transfers/forBlock for all transfers in a block. Required 'blockNumber'. Optional 'tokenAddress' to scope to a specific VIP‑180/721 contract and pagination. Use for 'transfers in block' or 'block activity'.

Inputs: blockNumber (required), page, size, cursor, +2 more. Returns: ok, data, error, network

getTransfersFromIndexer: Transfers from address (outgoing) (v1)A
Read-only

Query VeWorld Indexer /api/v1/transfers/from for outgoing transfers. Required 'address' (sender, accepts BOTH VNS names like roisin.vet AND 0x hex addresses). Optional 'tokenAddress' (accepts token symbol like VET, VTHO, B3TR OR 0x hex address) to scope to a specific VIP‑180/ERC-20 contract and pagination. Use for 'outgoing transfers' or 'payments from wallet'. NOTE: This is a directional filter of getTransfersOfAccount - prefer using getTransfersOfAccount unless you specifically need only outgoing transfers.

Inputs: address (required), page, size, cursor, +2 more. Returns: ok, data, error, network

getTransfersOfAccountIndexer: List transfers for wallet or token (v1)A
Read-only

Query transfer events using VeWorld Indexer /api/v1/transfers. Provide either 'address' (wallet, accepts BOTH VNS names like roisin.vet AND 0x hex addresses) or 'tokenAddress' (accepts token symbol like VET, VTHO, B3TR OR 0x hex address) plus optional pagination. Returns enriched transfers with VNS names and token symbols when available. Use for 'wallet transfers', 'token movements', or 'activity for contract/wallet'.

Inputs: page, size, cursor, address, +2 more. Returns: ok, data, error, network

getTransfersToIndexer: Transfers to address (incoming) (v1)A
Read-only

Query VeWorld Indexer /api/v1/transfers/to for incoming transfers. Required 'address' (recipient, accepts BOTH VNS names like roisin.vet AND 0x hex addresses). Optional 'tokenAddress' (accepts token symbol like VET, VTHO, B3TR OR 0x hex address) to scope to a specific VIP‑180/ERC-20 contract and pagination. Use for 'incoming transfers' or 'receipts to wallet'. NOTE: This is a directional filter of getTransfersOfAccount - prefer using getTransfersOfAccount unless you specifically need only incoming transfers.

Inputs: address (required), page, size, cursor, +2 more. Returns: ok, data, error, network

getValidatorBlockRewardsIndexer: Validator block rewards (v1)A
Read-onlyIdempotent

Fetch VTHO rewards per block via /api/v1/validators/blocks. Returns blockReward (base), priorityReward (mempool priority fees), total, and the split into delegatorRewards and validatorRewards. Filter by blockNumber, validator, and status. Use status=VALIDATED for produced blocks or status=MISSED for blocks the validator missed. Supports pagination and sort direction.

Inputs: page, size, cursor, status, +3 more. Returns: ok, data, error, network

getValidatorDelegationsIndexer: Validator delegations (v1)A
Read-onlyIdempotent

Retrieve delegation records via /api/v1/validators/delegations. Filter by validator, tokenId, and one or more statuses. Supports pagination and sort direction. Get information on delegations to a validator and the Stargate NFTs that are delegated to the validator

Inputs: page, size, cursor, tokenId, +3 more. Returns: ok, data, error, network

getValidatorMissedPercentageIndexer: Validator missed blocks percentage (v1)A
Read-onlyIdempotent

Calculate percentage of missed blocks for a validator in a block range via /api/v1/validators/blocks/missed/{validator}. Provide startBlock (inclusive) and endBlock (inclusive). Returns a percentage (0..100).

Inputs: validator (required), startBlock (required), endBlock. Returns: ok, data, error, network

getValidatorRegistryValidator Registry: list validator metadata (mainnet/testnet)A
Read-onlyIdempotent

Fetch validator metadata (name, location, description, website, logo) for the current network. Data source: validator-hub. Supports optional filtering by address.

Inputs: address. Returns: ok, data, error, network

getValidatorsIndexer: Validators (v1)A
Read-onlyIdempotent

Retrieve validator statistics via /api/v1/validators for Stargate NFT delegation decisions and validator performance. IMPORTANT: Look at all no status filter when getting validators when getting nft yields, when getting current validator not nft yields look at status=ACTIVE

KEY METRICS:

  • nftYieldsIfDelegatedNextCycle: Projected APY (%) for each Stargate NFT level in the next cycle if delegated to this validator (use this for delegation decisions)

  • nftYields: Current-cycle APY (%) for each Stargate NFT level already delegated to this validator

  • blockProbability: Validator's chance of producing blocks (higher = more rewards)

  • percentageOffline: Validator uptime reliability (lower = better)

  • delegatorTvl: Total USD value delegated by Stargate NFTs (higher = more competition)

FILTERS:

  • validatorId: Filter by specific validator address

  • endorser: Filter by endorser address

  • status: NONE, QUEUED, ACTIVE, EXITED, EXITING - only filter by ACTIVE for currently operating validators and all when getting nft yields

SORTING (sortBy parameter):

  • For NFT delegation: Use 'nft:' (e.g., 'nft:Dawn', 'nft:Thunder') to sort by APY IMPORTANT: When sorting by NFT yield, filter by status=ACTIVE or include QUEUED validators

  • Other options: validatorTvl, totalTvl, blockProbability, delegatorTvl

PAGINATION: Supports page, size, cursor, and direction (ASC/DESC)

VALIDATOR RECOMMENDATION GUIDELINES:

  1. Primary metric: nftYieldsIfDelegatedNextCycle[level] - this is APY percentage, NOT absolute VTHO

  2. Sort by the user's NFT level (e.g., sortBy='nft:Dawn' for Dawn NFTs)

  3. Filter to status=ACTIVE for currently operating validators

  4. Consider percentageOffline as secondary factor (reject if >30%)

  5. Present top 3-5 options with APY clearly labeled as percentage

Inputs: page, size, cursor, sortBy, +4 more. Returns: ok, data, error, network

getVeBetterDaoAppsVeBetterDAO: list xApps with on-chain status, roles and IPFS metadataA
Read-onlyIdempotent

List VeBetterDAO xApps directly from the on-chain X2EarnApps registry. For each app returns: id, on-chain name, owner (teamWalletAddress), createdAtTimestamp, roles (admin, moderators, creators, rewardDistributors), endorsement status (isEndorsed, endorsementScore vs threshold, isUnendorsed/grace period, isBlacklisted, isEligibleNow), whether the app is active in the current XAllocationVoting round, and IPFS metadata (description, website, logo, banner, social links, categories, distribution_strategy). Supports filtering to a single appId, to apps active in the current round, and by category (array of category ids, case-insensitive, OR semantics — sourced from IPFS metadata). Uses the VeChain SDK multicall for efficiency.

Inputs: appId, categories, includeRoles, includeMetadata, +4 more. Returns: ok, data, error, network

getVevoteHistoricProposalsVeVote: legacy historic proposalsA
Read-onlyIdempotent

Query legacy VeVote (Stakeholder and Steering Committee Governance contracts) historic proposals from /api/v1/vevote/historic-proposals. By default excludes test proposals (testProposals=false). Supports filtering by proposalId or legacy contractAddress and pagination.

Inputs: page, size, cursor, direction, +3 more. Returns: ok, data, error, network

getVevoteProposalResultsVeVote: proposal results (current governance)A
Read-onlyIdempotent

Fetch aggregated voting results per support from /api/v1/vevote/proposal/results. Optional filters: proposalId, support; supports pagination.

Inputs: page, size, cursor, support, +2 more. Returns: ok, data, error, network

listKnownContractsList contracts available to callContract / buildContractTransactionA
Read-onlyIdempotent

List the contracts the MCP server can talk to via the generic callContract and buildContractTransaction tools. For each entry returns the registry name (use this in clause.name), the on-chain addresses for mainnet and testnet, how many read / write / event fragments the ABI exposes, and whether an explicit address is required. The full ABI is NOT included to keep the context small — fetch it with getContractAbi when needed. Available categories: vebetterdao (B3TR, VOT3, governance, X2EarnApps, …), stargate (Stargate, StargateNFT, StargateDelegation, NodeManagement) and standard (erc20, erc721).

Inputs: category. Returns: ok, data, error, network

searchDiscourseForumSearch Discourse Forum (Optional)A
Read-onlyIdempotent

Search the VeBetterDAO Discourse forum (vechain.discourse.group) for topics, discussions, and community posts. Returns 10 results by default. OPTIONAL FEATURE: Requires Discourse MCP server running separately: npx -y @discourse/mcp@latest --transport http --site https://vechain.discourse.group. If not available, propose manually visiting forum links found in proposal descriptions. USE CASE: If a proposal's IPFS description doesn't contain a direct Discourse link, search by proposal ID or title to find related forum discussions.

Inputs: query (required), max_results, with_private.

searchDocsStargateSearch Stargate DocumentationC
Read-onlyIdempotent

Search the Stargate documentation

Inputs: query (required).

searchDocsVebetterDaoSearch VeBetterDao DocumentationB
Read-onlyIdempotent

Search the VeBetterDao documentation

Inputs: query (required).

searchDocsVechainSearch VeChain DocumentationA
Read-onlyIdempotent

Search the VeChain documentation

Inputs: query (required).

searchDocsVechainKitSearch VeChain Kit DocumentationB
Read-onlyIdempotent

Search the VeChain Kit documentation

Inputs: query (required).

searchDocsVevoteSearch VeVote DocumentationB
Read-onlyIdempotent

Search the VeVote documentation

Inputs: query (required).

thorDecodeEventThor Decode EventB
Read-onlyIdempotent

Decode an event emitted by a contract on Thor network

Inputs: data (required), topics (required), address (required). Returns: ok, data, error, network

thorGetAccountThor Get AccountA
Read-only

Get account details from Thor network

Inputs: address (required). Returns: ok, data, error, network

thorGetBlockThor Get BlockC
Read-onlyIdempotent

Get block details from Thor network

Inputs: blockRevision (required). Returns: ok, data, error, network

thorGetTransactionThor Get TransactionC
Read-onlyIdempotent

Get transaction details from Thor network

Inputs: transactionId (required). Returns: ok, data, error, network

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 76 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with detailed descriptions that prevent ambiguity. Even similar tools like getTransfersOfAccount, getTransfersFrom, getTransfersTo are explicitly differentiated by direction. The high number of tools is manageable because each targets a unique endpoint or action.

    Naming Consistency4/5

    Naming follows a consistent verb_noun pattern (e.g., getStargateNftHoldersTotal, callContract). Minor deviations exist such as thorGetBlock using a 'thor' prefix and 'getHistoryOfAccount' not matching the 'historic' pattern used elsewhere, but overall it's predictable.

    Tool Count2/5

    With 76 tools, the server is excessively large for a typical MCP server. While it covers many subdomains, the count overwhelms the purpose and could be consolidated (e.g., many Stargate time-series tools could be combined with parameters). This makes it harder for agents to navigate.

    Completeness4/5

    The server covers almost all aspects of the VeChain ecosystem: on-chain queries, staking, governance, token transfers, validators, and documentation. Minor gaps include lack of proposal creation tools and reliance on optional Discourse tools, but core workflows are well-supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers