VeChain MCP Server
OfficialOptional integration with Discourse forum to automatically fetch discussion content, analyze sentiment, and provide direct URLs to view discussions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@VeChain MCP Server Search VeChain documentation for VTHO"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
VeChain Documentation - Core VeChain blockchain documentation
VeChain Kit - VeChain development toolkit documentation
VeBetterDao - Decentralized governance platform documentation
VeVote - Voting platform documentation
Stargate - VeChain infrastructure documentation
Prerequisites
Node.js 20.18.1 or higher (required for running the server)
An MCP-compatible client such as:
Claude Desktop (macOS/Windows)
Cursor (code editor with MCP support)
Claude Code (CLI tool)
Available Tools
Documentation Search Tools
searchDocsVechain- Search VeChain documentationsearchDocsVechainKit- Search VeChain Kit documentationsearchDocsVebetterDao- Search VeBetterDao documentationsearchDocsVevote- Search VeVote documentationsearchDocsStargate- Search Stargate documentation
Thor Blockchain Tools
thorGetBlock- Get block informationthorGetTransaction- Get transaction detailsthorGetAccount- Get account informationthorDecodeEvent- Decode raw blockchain events
Token & NFT Tools
getTokenBalances- Get token balances for an accountgetTokenFiatPrice- Get fiat price for tokensgetTokenRegistry- Get token registry informationgetNFTs- Get NFTs owned by an accountgetNFTContracts- Get NFT contract information
B3TR & VeBetterDAO Tools
getB3TRGlobalOverview- Get B3TR global statisticsgetB3TRAppsLeaderboard- Get leaderboard of B3TR appsgetB3TRProposalsResults- Get B3TR proposal voting resultsgetB3TRProposalComments- Get on-chain voting commentsgetCurrentRound- Get current VeBetterDAO round infogetGMNFTStatus- Check GM NFT status for an account
Stargate Staking Tools
getStargateTotalVetStaked- Get total VET stakedgetStargateTokenRewards- Get staking rewardsgetValidators- Get validator information
Transaction & Transfer Tools
getTransactions- Get transactions for an accountgetTransfersOfAccount- Get token transfersgetHistoryOfAccount- 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
Locate your Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
Add the VeChain server configuration:
{
"mcpServers": {
"vechain": {
"command": "npx",
"args": ["-y", "@vechain/mcp-server@latest"],
"env": {
"VECHAIN_NETWORK": "mainnet"
}
}
}
}Restart Claude Desktop
For Cursor
Open Cursor Settings:
Press
Cmd/Ctrl + Shift + PType "Open MCP Settings" and select it
Add the VeChain server configuration (same JSON as above)
Restart Cursor
For Claude Code
Locate your Claude Code configuration file:
Create or edit
~/.claude/mcp.json
Add the VeChain server configuration (same JSON as above)
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+.
Pull the multi‑arch image (amd64/arm64):
docker pull ghcr.io/vechain/vechain-mcp-server:latestRun 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:latestFor 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.
Verify:
curl -fsS http://localhost:4000/healthList 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 /toolsandPOST /tools/callrequireAuthorization: Bearer <MCP_API_KEY>.GET /healthandGET /readyare 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
Clone the repository:
git clone https://github.com/vechain/vechain-mcp-server.git
cd vechain-mcp-serverInstall dependencies:
npm installBuild the project:
npm run buildDevelopment Modes
Option 1: STDIO Mode (Production-like)
Use this mode to test the server as it would run in production (via stdin/stdout).
Build the project (if not already done):
npm run buildConfigure 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.
Restart your MCP client
Note: For Claude Code and Cursor, the local configuration is already set up in
.claude/mcp.jsonand.cursor/mcp.jsonrespectively.
Option 2: HTTP Mode with Hot Reload (Active Development)
Use this mode when actively developing - it automatically reloads on file changes.
Start the development server:
npm run devThis starts an HTTP server on http://localhost:4000/mcp with file watching enabled.
Configure your MCP client to connect via HTTP:
{
"mcpServers": {
"vechain-local-dev": {
"url": "http://localhost:4000/mcp"
}
}
}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 inspectThis 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.groupImportant: 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 devRunning Automated Tests
Build and start the server:
npm run build
npm run startIn a separate terminal, run the test suite:
npm run testCode Quality
Format and lint your code before committing:
npm run format # Format code with Biome
npm run lint # Lint and fix issues with BiomeReleases
Releases are driven by git tags. Pushing a tag triggers a single
pipeline (.github/workflows/publish-release.yml) that:
Publishes the npm package to npmjs.org and to GitHub Packages.
Builds a multi-arch Docker image and pushes it to the dev and prod container registries.
Rolls the new image out to the dev environment automatically.
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 toolsbuildContractTransactionBuild a multi-clause transaction ready for the wallet to signADestructiveIdempotent
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 multicallARead-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-seriesARead-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 VeChainARead-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 appARead-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 userARead-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)ARead-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 leaderboardARead-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 leaderboardARead-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)ARead-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 commentsARead-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 resultsARead-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)ARead-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 summariesARead-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)ARead-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 leaderboardARead-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 contractARead-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)ARead-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 IDARead-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)ARead-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)ARead-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)ARead-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)ARead-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)ARead-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 statisticsARead-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)ARead-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 statusARead-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 accountARead-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 CIDARead-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 ownerARead-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 addressARead-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 periodARead-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 holdersARead-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)ARead-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 rewardsARead-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 tokensARead-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)ARead-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 stakedARead-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 claimedARead-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 accountARead-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 tokenARead-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 claimedARead-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 generatedARead-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 generatedARead-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 periodARead-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 periodARead-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 periodARead-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 periodARead-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 BalanceARead-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)ARead-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)ARead-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)ARead-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)ARead-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)ARead-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)ARead-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)ARead-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)ARead-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)ARead-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)ARead-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)ARead-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)ARead-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)ARead-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:
Primary metric: nftYieldsIfDelegatedNextCycle[level] - this is APY percentage, NOT absolute VTHO
Sort by the user's NFT level (e.g., sortBy='nft:Dawn' for Dawn NFTs)
Filter to status=ACTIVE for currently operating validators
Consider percentageOffline as secondary factor (reject if >30%)
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 metadataARead-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 proposalsARead-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)ARead-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 / buildContractTransactionARead-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)ARead-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 DocumentationCRead-onlyIdempotent
Search the Stargate documentation
Inputs: query (required).
searchDocsVebetterDaoSearch VeBetterDao DocumentationBRead-onlyIdempotent
Search the VeBetterDao documentation
Inputs: query (required).
searchDocsVechainSearch VeChain DocumentationARead-onlyIdempotent
Search the VeChain documentation
Inputs: query (required).
searchDocsVechainKitSearch VeChain Kit DocumentationBRead-onlyIdempotent
Search the VeChain Kit documentation
Inputs: query (required).
searchDocsVevoteSearch VeVote DocumentationBRead-onlyIdempotent
Search the VeVote documentation
Inputs: query (required).
thorDecodeEventThor Decode EventBRead-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 AccountARead-only
Get account details from Thor network
Inputs: address (required). Returns: ok, data, error, network
thorGetBlockThor Get BlockCRead-onlyIdempotent
Get block details from Thor network
Inputs: blockRevision (required). Returns: ok, data, error, network
thorGetTransactionThor Get TransactionCRead-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
Scored across 76 tools
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 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.
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.
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
Related MCP Connectors
Provide AI agents and automation tools with contextual access to blockchain data including balance…
ChainRay provides multi-chain blockchain data and intelligence for AI agents through 79 MCP tools across 57 supported networks, covering gas, chain data, wallets, DeFi, market, security, monitoring, and verifiable proofs. MCP access is available at https://mcp.chainray.online/mcp; paid HTTP capabilities settle via x402 on Base.
Carbon Voice MCP serves as a bridge that connects AI assistants like ChatGPT, Claude, and Cursor to a user's Carbon Voice account, turning voice messages and conversations into a private, on-demand knowledge base. It provides 28 specialized tools for comprehensive voice messaging management, including creating and sending messages, accessing conversation history with instant transcription, running AI actions (summarization, TLDR generation, meeting notes), and managing workspace collaboration through folders, contacts, and team communications.
AI Agent Utility Layer for agent safety, web monitoring, crypto research and tool discovery.
Related MCP Servers
- AlicenseAqualityNot gradedmaintenanceEnables AI assistants to interact with the Hive blockchain through the Model Context Protocol, allowing for account info retrieval, content reading/creation, cryptocurrency transfers, and cryptographic operations.1729 npm5ISC
- AlicenseBqualityDmaintenanceEnables interaction with the VeChain blockchain network, providing access to documentation search, Thor REST API queries for accounts/transactions/blocks, and wallet management with cryptographic signing capabilities for both Mainnet and Testnet.205MIT
- FlicenseNot gradedqualityBmaintenanceProvides AI assistants with up-to-date Vue ecosystem documentation through the Model Context Protocol, enabling semantic search, API lookup, and cross-framework references.16-
- AlicenseCqualityDmaintenanceEnables Claude Desktop to interact with the VeChain blockchain through natural language commands for token transfers, DEX trading, cross-chain bridges, NFT management, and VeBetter DAO operations.934MIT