Skip to main content
Glama
mcp-server-TLD

mcp-server-TLD

by bbsyaya

mcp-server-TLD

License: MIT TRON Network TypeScript MCP JustLend npm

A Model Context Protocol (MCP) server that enables AI agents to interact with the JustLend DAO lending protocol on TRON. Supply assets, borrow against collateral, manage positions, and analyze DeFi portfolios — all through a unified AI interface.

Beyond JustLend-specific operations, the server also exposes a full set of general-purpose TRON chain utilities — balance queries, block/transaction data, token metadata, TRX transfers, smart contract reads/writes, staking (Stake 2.0), multicall, and more.

Overview

JustLend DAO is the largest lending protocol on TRON, based on the Compound V2 architecture. This MCP server wraps the full protocol functionality into tools and guided prompts that AI agents (Claude Desktop, Cursor, etc.) can use.

šŸ“Œ Current Version: JustLend V1

This MCP server currently supports JustLend V1 protocol. All contract addresses, ABIs, calculation functions, and lending operations are for V1.

Key Capabilities

JustLend Protocol

  • Market Data: Real-time APYs, TVL, utilization rates, prices for all markets

    • Direct contract queries for on-chain accuracy

    • API-based queries for comprehensive market data (more stable, includes historical data and mining rewards)

  • Account Data: Full position analysis with API support

    • Contract-based: Health factor, collateral, borrow positions

    • API-based: Enhanced data with mining rewards, historical trends, risk metrics

  • Mining Rewards: Advanced mining reward calculation (based on justlend-app logic)

    • Detailed breakdown by market and reward token (USDD, TRX, WBTC, etc.)

    • Separates new period vs. last period rewards

    • USD value calculation with live token prices

    • Mining status tracking (ongoing/paused/ended) and period end times

  • Supply: Deposit TRX or TRC20 tokens to earn interest (mint jTokens)

  • Borrow: Borrow assets against your collateral with health factor monitoring

  • Repay: Repay outstanding borrows with full or partial amounts

  • Withdraw: Redeem jTokens back to underlying assets

  • Collateral Management: Enter/exit markets, manage what counts as collateral

  • Portfolio Analysis: AI-guided risk assessment, health factor monitoring, optimization

  • Token Approvals: Manage TRC20 approvals for jToken contracts

  • JST Voting / Governance: View proposals, cast votes, deposit/withdraw JST for voting power, reclaim votes

General TRON Chain

  • Balances: TRX balance (with Sun/TRX conversion), TRC20/TRC1155 token balances

  • Blocks: Latest block, block by number/hash, block number, chain ID

  • Transactions: Fetch transaction details, receipts, wait for confirmation

  • Contracts: Read/write any contract, fetch on-chain ABI, multicall (v2 & v3), deploy, estimate energy

  • Token Metadata: TRC20 info (name/symbol/decimals/supply), TRC721 metadata, TRC1155 URI

  • Transfers: Send TRX, transfer TRC20 tokens, approve spenders

  • Staking (Stake 2.0): Freeze/unfreeze TRX for BANDWIDTH or ENERGY, withdraw expired unfreeze

  • Address Utilities: Hex ↔ Base58 conversion, address validation, resolution

  • Wallet: Sign messages, sign typed data (EIP-712), HD wallet derivation from mnemonic

Related MCP server: mcp-server-tron

Supported Markets

jToken

Underlying

Description

jTRX

TRX

Native TRON token

jUSDT

USDT

Tether USD

jUSDC

USDC

USD Coin

jBTC

BTC

Bitcoin (wrapped)

jETH

ETH

Ethereum (wrapped)

jSUN

SUN

SUN token

jWIN

WIN

WINkLink

jTUSD

TUSD

TrueUSD

Prerequisites

Installation

git clone https://github.com/your-org/mcp-server-TLD.git
cd mcp-server-TLD
npm install

Configuration

Environment Variables

SECURITY: Never save private keys in config files. Use environment variables.

# Required for write operations (supply, borrow, transfer, stake, etc.)
export TRON_PRIVATE_KEY="your_private_key_hex"
# OR use a mnemonic phrase
export TRON_MNEMONIC="word1 word2 ... word12"
export TRON_ACCOUNT_INDEX="0"   # Optional HD wallet account index, default: 0

# Strongly recommended — avoids TronGrid 429 rate limiting on mainnet
export TRONGRID_API_KEY="your_trongrid_api_key"

Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "justlend": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-server-TLD/src/index.ts"],
      "env": {
        "TRONGRID_API_KEY": "your_key"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "justlend": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-server-TLD/src/index.ts"]
    }
  }
}

Usage

# Stdio mode (for MCP clients)
npm start

# HTTP/SSE mode (for remote clients)
npm run start:http

# Development with auto-reload
npm run dev

API Reference

Tools (34 total)

Wallet & Network

Tool

Description

Write?

get_wallet_address

Show configured wallet address

No

get_supported_networks

List available networks

No

get_supported_markets

List all jToken markets with addresses

No

Market Data

Tool

Description

Write?

get_market_data

Detailed data for one market (APY, TVL, rates) - Contract query

No

get_all_markets

Overview of all markets - Contract query

No

get_protocol_summary

Comptroller config & protocol parameters - Contract query

No

get_markets_from_api

[API] All market data with mining rewards & trends

No

get_dashboard_from_api

[API] Protocol-level statistics (TVL, users, etc.)

No

get_jtoken_details_from_api

[API] Detailed jToken info with interest rate model

No

Account & Balances

Tool

Description

Write?

get_account_summary

Full position: supplies, borrows, health factor - Contract query

No

get_account_data_from_api

[API] Enhanced account data with mining rewards & trends

No

check_allowance

Check TRC20 approval for jToken

No

get_trx_balance

TRX balance

No

get_token_balance

TRC20 token balance

No

Lending Operations

Tool

Description

Write?

supply

Deposit assets to earn interest

Yes

withdraw

Withdraw supplied assets

Yes

withdraw_all

Withdraw all from a market

Yes

borrow

Borrow against collateral

Yes

repay

Repay outstanding borrows

Yes

enter_market

Enable market as collateral

Yes

exit_market

Disable market as collateral

Yes

approve_underlying

Approve TRC20 for jToken

Yes

claim_rewards

Claim mining rewards

Yes

JST Voting / Governance

Tool

Description

Write?

get_proposal_list

List all governance proposals with status and vote counts

No

get_user_vote_status

User's voting history: voted proposals, withdrawable votes

No

get_vote_info

Voting power: JST balance, available votes, locked votes

No

get_locked_votes

Votes locked in a specific proposal

No

check_jst_allowance_for_voting

Check JST approval for WJST voting contract

No

approve_jst_for_voting

Approve JST for the WJST voting contract

Yes

deposit_jst_for_votes

Deposit JST to get voting power (1 JST = 1 Vote)

Yes

withdraw_votes_to_jst

Withdraw WJST back to JST

Yes

cast_vote

Cast for/against votes on a proposal

Yes

withdraw_votes_from_proposal

Reclaim votes from completed proposals

Yes

Prompts (AI-Guided Workflows)

Prompt

Description

supply_assets

Step-by-step supply with balance checks and approval

borrow_assets

Safe borrowing with risk assessment and health factor checks

repay_borrow

Guided repayment with verification

analyze_portfolio

Comprehensive portfolio analysis with risk scoring

compare_markets

Find best supply/borrow opportunities

Architecture

mcp-server-TLD/
ā”œā”€ā”€ src/
│   ā”œā”€ā”€ core/
│   │   ā”œā”€ā”€ chains.ts          # Network configs + JustLend contract addresses
│   │   ā”œā”€ā”€ abis.ts            # jToken, Comptroller, Oracle, TRC20 ABIs
│   │   ā”œā”€ā”€ tools.ts           # MCP tool registrations
│   │   ā”œā”€ā”€ prompts.ts         # AI-guided workflow prompts
│   │   ā”œā”€ā”€ resources.ts       # Static protocol info resource
│   │   └── services/
│   │       ā”œā”€ā”€ # — JustLend-specific —
│   │       ā”œā”€ā”€ clients.ts     # TronWeb client factory (cached)
│   │       ā”œā”€ā”€ wallet.ts      # Key/mnemonic management, signMessage, signTypedData
│   │       ā”œā”€ā”€ markets.ts     # APY, TVL, utilization, prices
│   │       ā”œā”€ā”€ account.ts     # User positions, liquidity, allowances
│   │       ā”œā”€ā”€ lending.ts     # supply, borrow, repay, withdraw, collateral
│   │       ā”œā”€ā”€ voting.ts      # JST governance: proposals, cast vote, deposit/withdraw WJST
│   │       ā”œā”€ā”€ # — General TRON chain —
│   │       ā”œā”€ā”€ address.ts     # Hex ↔ Base58 conversion, validation
│   │       ā”œā”€ā”€ balance.ts     # TRX balance (rich), TRC20/TRC1155 balances
│   │       ā”œā”€ā”€ blocks.ts      # Block queries, block number, chain ID
│   │       ā”œā”€ā”€ transactions.ts# getTransaction, getTransactionInfo, waitForTransaction
│   │       ā”œā”€ā”€ transfer.ts    # transferTRX, transferTRC20, approveTRC20
│   │       ā”œā”€ā”€ tokens.ts      # TRC20/TRC721/TRC1155 metadata
│   │       ā”œā”€ā”€ contracts.ts   # readContract, writeContract, multicall, deploy, estimateEnergy
│   │       ā”œā”€ā”€ multicall-abi.ts # Multicall2 & Multicall3 ABIs
│   │       ā”œā”€ā”€ staking.ts     # Stake 2.0: freeze, unfreeze, withdrawExpireUnfreeze
│   │       └── utils.ts       # toSun/fromSun, formatJson, hexToNumber, isAddress, …
│   ā”œā”€ā”€ server/
│   │   ā”œā”€ā”€ server.ts          # MCP server init
│   │   └── http-server.ts     # Express HTTP/SSE transport
│   └── index.ts               # Stdio entry point
ā”œā”€ā”€ bin/cli.js                 # CLI entry for npx
└── tests/
    └── core/
        ā”œā”€ā”€ chains.test.ts
        └── services/
            ā”œā”€ā”€ services.test.ts    # Client cache, legacy balance tests
            ā”œā”€ā”€ address.test.ts     # Pure: address format conversion (16 tests)
            ā”œā”€ā”€ utils.test.ts       # Pure: unit conversions, formatters (26 tests)
            ā”œā”€ā”€ balance.test.ts     # Integration: TRX & TRC20 balances
            ā”œā”€ā”€ blocks.test.ts      # Integration: block queries
            ā”œā”€ā”€ contracts.test.ts   # Mixed: pure ABI helpers + integration reads
            ā”œā”€ā”€ tokens.test.ts      # Integration: TRC20 token metadata
            ā”œā”€ā”€ transactions.test.ts# Integration: transaction fetch
            ā”œā”€ā”€ transfer.test.ts    # Write: skipped by default (TEST_TRANSFER=1)
            ā”œā”€ā”€ staking.test.ts     # Write: skipped by default (TEST_STAKING=1)
            └── wallet.test.ts      # Unit: skipped without TRON_PRIVATE_KEY

Testing

# Run all tests (pure/unit tests always pass; integration tests need network)
npm test

# Run individual test files (recommended to avoid TronGrid rate limits)
npx vitest run tests/core/services/utils.test.ts
npx vitest run tests/core/services/address.test.ts
npx vitest run tests/core/services/balance.test.ts
npx vitest run tests/core/services/blocks.test.ts
npx vitest run tests/core/services/contracts.test.ts
npx vitest run tests/core/services/transactions.test.ts
npx vitest run tests/core/services/tokens.test.ts

# Enable write/staking tests (uses real funds — use Nile testnet!)
TRON_PRIVATE_KEY=xxx TEST_TRANSFER=1 npx vitest run tests/core/services/transfer.test.ts
TRON_PRIVATE_KEY=xxx TEST_STAKING=1 npx vitest run tests/core/services/staking.test.ts

Rate limiting: Integration tests make real RPC calls to TronGrid. Without TRONGRID_API_KEY the free tier limits to a few requests per second. Run test files individually, or set TRONGRID_API_KEY to avoid 429 errors.

Security Considerations

  • Private keys are read from environment variables only, never exposed via MCP tools

  • Write operations are clearly marked with destructiveHint: true in MCP annotations

  • Health factor checks in prompts prevent dangerous borrowing

  • Always test on Nile testnet before mainnet operations

  • Be cautious with unlimited approvals (approve_underlying with max)

  • Never share your claude_desktop_config.json if it contains keys

Example Conversations

"What are the best supply rates on JustLend right now?" → AI calls get_all_markets, sorts by supplyAPY, presents ranking

"I want to supply 10,000 USDT to earn interest" → AI uses supply_assets prompt: checks balance → approves USDT → supplies → verifies

"Am I at risk of liquidation?" → AI calls get_account_summary, analyzes health factor, warns if < 1.5

"Borrow 500 USDT against my TRX collateral" → AI uses borrow_assets prompt: checks collateral → calculates new health factor → executes if safe

"What is the TRX balance of address TXxx...?" → AI calls the general-purpose TRX balance tool, returns balance in both TRX and Sun

"Freeze 100 TRX for ENERGY" → AI calls staking service to freeze via Stake 2.0, returns transaction hash

"Show me the latest governance proposals" → AI calls get_proposal_list, displays proposals sorted by ID with status and vote counts

"I want to vote for proposal #425 with 1000 JST" → AI checks get_vote_info → if no votes, suggests approve_jst_for_voting + deposit_jst_for_votes → then cast_vote

"Withdraw my votes from completed proposals" → AI calls get_user_vote_status to find withdrawable proposals → calls withdraw_votes_from_proposal for each

License

MIT

Available Tools

37 tools
approve_jst_for_votingA
Idempotent

Approve JST token for the WJST voting contract. Required before depositing JST to get voting power. Use amount='max' for unlimited approval.

Inputs: amount, network.

approve_underlyingA
Idempotent

Approve the jToken contract to spend your underlying TRC20 tokens. Required before supply() or repay() for TRC20-backed markets (not needed for jTRX). Use amount='max' for unlimited approval. Typical cost: ~23,000 energy + ~265 bandwidth.

Inputs: market (required), amount, network.

borrowA
Destructive

Borrow assets from a JustLend market against your collateral. You must have entered a market as collateral (enter_market) and have sufficient liquidity. Check your account_summary and health_factor before borrowing. Typical cost: ~100,000 energy + ~313 bandwidth.

Inputs: amount (required), market (required), network.

cast_voteA
Destructive

Cast a vote on a governance proposal. You must have available votes (deposit JST first if needed). Support: true = vote FOR, false = vote AGAINST. You can add more votes to a proposal you already voted on.

Inputs: votes (required), support (required), proposalId (required), network.

check_allowanceA
Read-onlyIdempotent

Check if the underlying TRC20 token has been approved for a jToken market. Must be approved before supply() or repay() for TRC20 markets. Not needed for jTRX.

Inputs: market (required), address, network.

check_jst_allowance_for_votingA
Read-onlyIdempotent

Check if JST has been approved for the WJST voting contract. Must be approved before depositing JST to get votes.

Inputs: address, network.

claim_rewardsA

Claim accrued JustLend mining rewards for the configured wallet. Typical cost: ~60,000 energy + ~330 bandwidth.

Inputs: network.

deposit_jst_for_votesA
Destructive

Deposit JST into the WJST contract to get voting power. Requires prior approval of JST for the WJST contract (use approve_jst_for_voting first). 1 JST = 1 Vote. Deposited JST can be withdrawn back after voting.

Inputs: amount (required), network.

enter_marketA
Idempotent

Enable a jToken market as collateral. Required before borrowing against supplied assets. Once entered, your supply in this market counts towards your borrowing capacity. Typical cost: ~80,000 energy + ~300 bandwidth.

Inputs: market (required), network.

estimate_lending_energyA
Read-onlyIdempotent

Estimate energy, bandwidth, and TRX cost for any JustLend operation BEFORE executing it. Covers ALL operations: supply, withdraw, withdraw_all, borrow, repay, approve, enter_market, exit_market, claim_rewards. Tries on-chain simulation first; falls back to historical typical values if simulation fails. Returns per-step breakdown (e.g. approve + mint for supply), total energy, total bandwidth, and estimated TRX cost. For supply/repay: automatically checks current allowance — if sufficient, the approve step is skipped. For approve: supports custom spender address (not just jToken). Use this tool whenever the user asks about gas/energy/cost for any lending operation.

Inputs: market (required), operation (required), amount, address, +2 more.

exit_marketA
Destructive

Disable a jToken market as collateral. Will fail if doing so would make your account undercollateralized. Check account_summary first to ensure safety. Typical cost: ~50,000 energy + ~280 bandwidth.

Inputs: market (required), network.

get_account_data_from_apiA
Read-onlyIdempotent

Get user account data from JustLend API. More stable and comprehensive than contract queries. Returns lending positions, balances, mining rewards, health factor, etc.

Inputs: address, network.

get_account_summaryA
Read-onlyIdempotent

Get a comprehensive view of a user's JustLend positions: supply balances, borrow balances, collateral status, health factor, liquidation risk, and USD values for each market.

Inputs: address, network.

get_all_marketsA
Read-onlyIdempotent

Get overview data for ALL JustLend markets including supply APY, borrow APY, mining rewards APY, underlying staking yield, total supply APY, and TVL. Mining APY is calculated from on-chain supply mining programs (USDD/TRX dual mining, WBTC mining, etc.). totalSupplyAPY = base supply APY + underlying staking APY + mining APY.

Inputs: network.

get_dashboard_from_apiA
Read-onlyIdempotent

Get JustLend protocol dashboard from API. Returns protocol-level statistics: total supply, total borrow, TVL, number of suppliers/borrowers, etc.

Inputs: network.

get_jtoken_details_from_apiB
Read-onlyIdempotent

Get detailed jToken information from API. Returns comprehensive market details including interest rate model, reserve info, etc.

Inputs: jtokenAddr (required), network.

get_locked_votesA
Read-onlyIdempotent

Get the number of votes a user has locked in a specific proposal.

Inputs: proposalId (required), address, network.

get_market_dataA
Read-onlyIdempotent

Get detailed market data for a specific JustLend market: supply/borrow APY, TVL, utilization, collateral factor, price, and status. Use jToken symbol like 'jUSDT' or 'jTRX'.

Inputs: market (required), network.

get_markets_from_apiA
Read-onlyIdempotent

Get all market data from JustLend API. More stable than contract queries. Returns comprehensive market data including APY, TVL, utilization, prices, mining rewards, etc.

Inputs: network.

get_mining_rewardsA
Read-onlyIdempotent

Get mining rewards for supply markets (USDD, WBTC, etc.). Returns unclaimed rewards, mining APY, and reward breakdown from API.

Inputs: address, network.

get_proposal_listA
Read-onlyIdempotent

Get the list of JustLend DAO governance proposals. Returns proposals with their status (Active, Passed, Defeated, etc.), vote counts, and details. Sorted by newest first.

Inputs: limit, network.

get_protocol_summaryA
Read-onlyIdempotent

Get JustLend protocol-level info: Comptroller config, close factor, liquidation incentive, total markets.

Inputs: network.

get_supported_marketsA
Read-onlyIdempotent

List all available JustLend lending markets (jTokens) with their addresses and underlying assets.

Inputs: network.

get_supported_networksA
Read-onlyIdempotent

List all supported TRON networks for JustLend.

Inputs: no named parameters.

get_token_balanceA
Read-onlyIdempotent

Get TRC20 token balance for an address. You can pass either a token symbol (e.g. 'USDD', 'USDT', 'ETH') or a contract address. When using a symbol, it resolves to the correct contract address from JustLend markets automatically. IMPORTANT: Always prefer using token symbols over raw addresses to avoid using outdated/wrong contract addresses. For example, use 'USDD' instead of a raw address — the old USDD (TPYmHEhy5n8TCEfYGqW2rPxsghSfzghPDn) is deprecated. The returned balance is already formatted in human-readable token units (decimals already applied). Do NOT divide the balance by decimals again.

Inputs: token, address, network, tokenAddress.

get_trx_balanceB
Read-onlyIdempotent

Get TRX balance for an address.

Inputs: address, network.

get_usdd_mining_configA
Read-onlyIdempotent

Get USDD mining configuration including mining periods, reward tokens (USDD/TRX dual mining), and schedule.

Inputs: no named parameters.

get_user_vote_statusA
Read-onlyIdempotent

Get a user's voting status across all governance proposals. Shows which proposals the user has voted on, their vote amounts (for/against/abstain), and which proposals have withdrawable votes.

Inputs: address, network.

get_vote_infoA
Read-onlyIdempotent

Get voting power info for a user: JST wallet balance, available (surplus) votes, total deposited votes, and votes currently cast in proposals. This is the key tool to check before voting — it shows how many votes are available to use.

Inputs: address, network.

get_wallet_addressA
Read-onlyIdempotent

Get the configured wallet address. This wallet is used for all lending operations.

Inputs: no named parameters.

get_wbtc_mining_configB
Read-onlyIdempotent

Get WBTC mining configuration and supply mining activity details.

Inputs: no named parameters.

repayA
Destructive

Repay borrowed assets to a JustLend market. For TRC20 markets, must have approved underlying first. Use amount='max' to repay the full outstanding borrow. Typical cost: 80,00090,000 energy + 280320 bandwidth (TRX costs less than TRC20).

Inputs: amount (required), market (required), network.

supplyA
Destructive

Supply (deposit) assets into a JustLend market to earn interest. For TRC20 markets, you must first call approve_underlying. For jTRX, TRX is sent directly. Returns a jToken balance representing your deposit. Typical cost: ~100,000 energy + ~310 bandwidth for TRC20, ~80,000 energy + ~280 bandwidth for TRX. Use estimate_lending_energy tool for precise estimates before executing.

Inputs: amount (required), market (required), network.

withdrawA
Destructive

Withdraw (redeem) supplied assets from a JustLend market. Specify the amount in underlying units. May fail if assets are used as collateral for active borrows. Typical cost: ~90,000 energy + ~300 bandwidth.

Inputs: amount (required), market (required), network.

withdraw_allA
Destructive

Withdraw ALL supplied assets from a JustLend market by redeeming all jTokens. Typical cost: ~90,000 energy + ~300 bandwidth.

Inputs: market (required), network.

withdraw_votes_from_proposalA
Destructive

Withdraw (reclaim) votes from a completed or canceled proposal. Only works for proposals that are no longer active. After withdrawing, the votes become available again for other proposals or can be converted back to JST.

Inputs: proposalId (required), network.

withdraw_votes_to_jstA
Destructive

Withdraw WJST back to JST. Can only withdraw votes that are not currently locked in active proposals. Use get_vote_info to check your surplus (available) votes before withdrawing.

Inputs: amount (required), network.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 37 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some overlap among data retrieval tools like get_market_data, get_all_markets, and get_markets_from_api, which provide similar market information from different sources. Descriptions help differentiate, but an agent might still select the wrong one without careful analysis.

    Naming Consistency5/5

    Tool names consistently follow a verb_noun pattern with underscores (e.g., get_wallet_address, approve_underlying, cast_vote). Even longer names like get_markets_from_api and get_jtoken_details_from_api maintain this pattern, making the naming predictable and easy to understand.

    Tool Count3/5

    With 37 tools, the set is somewhat large for a single lending protocol. While many are necessary for comprehensive coverage (including governance and helper tools), some like the multiple market data tools could be consolidated, making the count feel slightly excessive for the apparent scope.

    Completeness5/5

    The tool set covers all core lending operations (supply, withdraw, borrow, repay, collateral management, approvals) plus governance (voting, depositing votes) and utility tools (balance checks, energy estimation). There are no obvious gaps for a user interacting with JustLend protocol.

    Related MCP Connectors

    Related MCP Servers