# Mcp Server Justlend

> MCP server from justlend/mcp-server-justlend.

- **Type:** MCP server
- **Install:** `agentstack add mcp-justlend-mcp-server-justlend`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [justlend](https://agentstack.voostack.com/s/justlend)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [justlend](https://github.com/justlend)
- **Source:** https://github.com/justlend/mcp-server-justlend

## Install

```sh
agentstack add mcp-justlend-mcp-server-justlend
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp-server-justlend

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, participate in V2 (Moolah) isolated markets and vaults, 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](https://justlend.org) is the largest lending protocol on TRON. This MCP server wraps the full protocol functionality into tools and guided prompts that local MCP clients such as Claude Desktop, Codex, Claude Code, and Cursor can use.

**📌 Current Version: v1.1.2 — JustLend V1 + V2 (Moolah), plus TRX↔WTRX wrap/unwrap**

- **JustLend V1** (Compound V2 fork): the original pool-based protocol — `jUSDT`, `jTRX`, `jUSDD`, `jSUN`, `jWBTC`, etc. Full supply / borrow / repay / withdraw / collateral management and mining rewards.
- **JustLend V2 (Moolah)** (Morpho Blue fork): isolated markets with `MarketParams (loanToken, collateralToken, oracle, irm, lltv)` and ERC4626 vaults that auto-allocate across markets. Full vault deposit / redeem, collateral supply / borrow / repay / liquidate, and public liquidations.

### Key Capabilities

#### JustLend V1 (pool-based, Compound V2 fork)
- **Market Data**: Real-time APYs, TVL, utilization rates, prices for all markets
  - Smart fallback: contract queries first, API fallback for reliability
  - TTL caching (30–60s) to reduce RPC calls
- **Account Data**: Full position analysis via Multicall3 batch queries (~2.5s vs ~8s legacy)
  - Health factor, collateral, borrow positions
  - On-chain Oracle prices with API fallback
- **Batch Wallet Balances**: Query all TRC20 token balances in a single Multicall3 RPC call
- **Mining Rewards**: Advanced mining reward calculation (based on justlend-app logic)
  - Detailed breakdown by market and reward token (USDD, TRX, WBTC, etc.)
  - USD value calculation with live token prices
- **Supply / Borrow / Repay / Withdraw**: Full lending operations with pre-flight checks
- **Collateral Management**: Enter/exit markets, manage what counts as collateral
- **Portfolio Analysis**: AI-guided risk assessment, health factor monitoring, optimization
- **JST Voting / Governance**: View proposals, cast votes, deposit/withdraw JST for voting power, reclaim votes
- **Energy Rental**: Rent energy from JustLend, calculate rental prices, query rental orders, return/cancel rentals
- **sTRX Staking**: Stake TRX to receive sTRX, unstake sTRX, claim staking rewards, check withdrawal eligibility
  - Precision-safe BigInt/string math for TRX Sun conversion and 18-decimal sTRX balances/exchange-rate display

#### JustLend V2 — Moolah (New in v1.1.0)
- **ERC4626 Vaults** (TRX / USDT / USDD on mainnet; TRX + USDT on nile): auto-compounding yield with a curator that allocates deposits across isolated markets. Deposit / withdraw (by asset amount or `max`) / redeem (by shares) with TRC20 approvals handled as a separate tool so LLMs can reason about each step.
- **Isolated Markets**: each market is a `(loanToken, collateralToken, oracle, irm, lltv)` tuple. Supply collateral → borrow → repay → withdraw collateral, plus a composite `moolah_borrow` that handles collateral+borrow as two sequential txs. TRX routes through the `TrxProviderProxy` contract; TRC20 goes through `MoolahProxy` directly.
- **Public Liquidations**: list undercollateralized positions (`risk > 1.0`), quote loan-token requirement for a target seize, execute liquidation. Includes an explicit `approve_liquidator_token` step.
- **Dashboard + History**: aggregated user position, APY / TVL time-series for vaults and markets, paginated V2 transaction records.
- **Gas estimation**: `estimate_moolah_energy` returns typical historical energy / bandwidth / TRX cost for every V2 write op.

#### Historical records (New in v1.1.0)
- Paginated REST wrappers for V1 lending / sTRX / voting / energy-rental / liquidation history, plus V2 Moolah records. Each endpoint's numeric action/op codes are enriched with human-readable names (`actionName` / `opName`) client-side so MCP tools are self-describing.

#### Browser Wallet Signing
- **TronLink Integration**: Connect TronLink (and other TIP-6963 browser wallets) via the `tronlink-signer` SDK
- **Sign-only mode**: Server builds transactions, browser only signs — private keys never leave the wallet
- **Confirmable transaction summaries**: Contract writes pass a deterministic summary (network, contract, function, args, callValue, feeLimit, simulation status) to the signer
- **Dual wallet mode**: Users choose between `browser` (recommended) or `agent` (encrypted local storage)

#### 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
  - Transfer/approval paths validate recipient, token, and spender TRON addresses before signing
- **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, secure key management via agent-wallet or browser wallet

## Supported Markets

### JustLend V1 (pool-based)

The protocol currently exposes **17 active + 6 paused legacy = 23 markets**. Call `get_supported_markets` for the live list with addresses; the active markets are:

| jToken     | Underlying | Description |
|------------|-----------|-------------|
| jTRX       | TRX       | Native TRON token |
| jUSDT      | USDT      | Tether USD |
| jUSDD      | USDD      | Decentralized USD (USDD/TRX supply‑mining rewards) |
| jUSD1      | USD1      | World Liberty Financial USD |
| jTUSD      | TUSD      | TrueUSD |
| jwstUSDT   | wstUSDT   | Wrapped staked USDT (yields underlying staking APY) |
| jsTRX      | sTRX      | Staked TRX (yields underlying staking APY) |
| jBTC       | BTC       | Bitcoin (wrapped) |
| jWBTC      | WBTC      | Wrapped Bitcoin |
| jETH       | ETH       | Ethereum — dApp UI displays as "ETH" (formerly "ETHOLD") |
| jETHB      | ETHB      | Bridged Ethereum — dApp UI displays as "ETHB" (formerly "ETH") |
| jSUN       | SUN       | SUN token |
| jJST       | JST       | JUST governance token |
| jWIN       | WIN       | WINkLink |
| jBTT       | BTT       | BitTorrent token |
| jNFT       | NFT       | APENFT |
| jHTX       | HTX       | HTX token |

Paused / legacy markets (closed to new supply/borrow, queryable for read & to unwind positions): `jUSDCOLD`, `jUSDD_OLD`, `jBUSDOLD`, `jSUNOLD`, `jUSDJ`, `jWBTT`.

### JustLend V2 (Moolah) — vaults

| Vault | Underlying | Mainnet | Nile |
|-------|-----------|---------|------|
| TRX   | native TRX | ✅ | ✅ |
| USDT  | TRC20 USDT | ✅ | ✅ (different underlying address from mainnet) |
| USDD  | TRC20 USDD | ✅ | ❌ (not deployed on nile) |

Markets are not enumerated here because they are created dynamically on-chain; use `get_moolah_markets` to list them at runtime (each market returns a `marketId` / `id` plus `loanSymbol` / `collateralSymbol` / `lltv` / rates).

## Prerequisites

- [Node.js](https://nodejs.org/) 20.0.0 or higher
- Optional: [TronGrid API key](https://www.trongrid.io/) for reliable mainnet access (strongly recommended)

## Installation

```bash
git clone https://github.com/justlend/mcp-server-justlend.git
cd mcp-server-justlend
npm install
```

## Quick Setup

For a guided setup experience (build, configure, generate `.mcp.json`, print Codex setup command):

```bash
bash scripts/setup-mcp-test.sh
# Add --claude-desktop to also print Claude Desktop JSON
```

The script checks Node.js 20+, installs dependencies, builds the project, generates local Claude Code config, and prints the local Codex registration command.

## Configuration

### Wallet Setup (First-Use Choice)

On first use, the server does **not** force a wallet choice. Users can explicitly choose between:

1. `browser` mode via TronLink using `connect_browser_wallet`
2. `agent` mode via encrypted local wallet using `set_wallet_mode` with `mode="agent"`

Private keys are **never** stored in environment variables by default. If the user selects `agent` mode, the encrypted wallet is stored in `~/.agent-wallet/`.

You can also manage wallets via **CLI** or **MCP tools**:

#### CLI (agent-wallet)
```bash
# Import an existing private key or mnemonic
npx agent-wallet add

# Generate a new wallet
npx agent-wallet generate

# List all wallets
npx agent-wallet list

# Switch active wallet
npx agent-wallet activate 
```

#### MCP Tools (runtime)

| Tool | Description |
|------|-------------|
| `get_wallet_address` | Shows current address, or returns first-use wallet selection guidance |
| `connect_browser_wallet` | Connect TronLink / browser wallet for signing |
| `set_wallet_mode` | Switch between `browser` and `agent` signing |
| `get_wallet_mode` | Show current signing mode and addresses |
| `list_wallets` | List all wallets with IDs, types, addresses |
| `set_active_wallet` | Switch active wallet by ID |

Importing an existing private key is intentionally not exposed as an MCP tool because MCP arguments can be logged by clients and transports. Use the CLI instead:

```bash
npx agent-wallet import
```

```bash
# (Optional) For automated/CI setups, set the wallet password
export AGENT_WALLET_PASSWORD="your_wallet_password"

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

### Client Configuration

Build the local server first:

```bash
npm run build
```

All local client examples below use the built stdio entrypoint:

```bash
node /absolute/path/to/mcp-server-justlend/build/index.js
```

#### Claude Desktop

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

```json
{
  "mcpServers": {
    "justlend": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-justlend/build/index.js"],
      "env": {
        "TRONGRID_API_KEY": "SET_VIA_SYSTEM_ENV"
      }
    }
  }
}
```

#### Codex

Recommended: register the local stdio server with `codex mcp add`:

```bash
codex mcp add justlend --env TRONGRID_API_KEY=your_trongrid_api_key -- \
  node /absolute/path/to/mcp-server-justlend/build/index.js
```

If you do not want to set a TronGrid key yet, omit the `--env` flag:

```bash
codex mcp add justlend -- node /absolute/path/to/mcp-server-justlend/build/index.js
```

Useful maintenance commands:

```bash
codex mcp list
codex mcp get justlend
codex mcp remove justlend
```

#### Claude Code

Add to `.mcp.json` in the project root:

```json
{
  "mcpServers": {
    "justlend": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-justlend/build/index.js"],
      "env": {
        "TRONGRID_API_KEY": "SET_VIA_SYSTEM_ENV"
      }
    }
  }
}
```

#### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "justlend": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-justlend/build/index.js"],
      "env": {
        "TRONGRID_API_KEY": "SET_VIA_SYSTEM_ENV"
      }
    }
  }
}
```

## Usage

The server supports two transport modes. Both share the same Tools, Resources, and wallet initialization — the difference is how clients connect.

### Stdio Mode (Local AI Clients)

```bash
npm start
```

The server communicates via stdin/stdout. This is the standard mode for local MCP clients like **Claude Desktop**, **Codex**, **Claude Code**, and **Cursor**, which launch the server as a child process.

### HTTP/SSE Mode (Remote / Multi-Client)

```bash
MCP_API_KEY=my-secret-key npm run start:http
```

The server starts an Express HTTP service with Server-Sent Events (SSE) transport. Suitable for **web applications**, **remote clients**, or scenarios where **multiple clients** need to connect concurrently.

HTTP mode is fail-closed: `MCP_API_KEY` is required, the server binds to `127.0.0.1` by default, and CORS is disabled unless you explicitly set `MCP_CORS_ORIGIN`.

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/sse` | GET | SSE connection endpoint — returns a `sessionId` |
| `/messages?sessionId=xxx` | POST | Send MCP messages for a session |
| `/health` | GET | Health check (no auth required) |

**Environment variables:**

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `3001` | HTTP listen port |
| `MCP_HOST` | `127.0.0.1` | HTTP listen host. Keep the default unless you intentionally want remote exposure. |
| `MCP_API_KEY` | _(required)_ | Bearer token for authentication. HTTP mode refuses to start without it. |
| `MCP_CORS_ORIGIN` | _(disabled)_ | Allowed CORS origin. If unset, no CORS headers are sent. |
| `MCP_MAX_SESSIONS` | `100` | Maximum concurrent SSE sessions |
| `MCP_SESSION_TIMEOUT_MS` | `1800000` | Session idle timeout in ms (default: 30 min) |

Example with authentication:

```bash
MCP_API_KEY=my-secret-key PORT=8080 npm run start:http
```

```bash
# Connect from client
curl -H "Authorization: Bearer my-secret-key" http://localhost:8080/sse
```

### Development

```bash
npm run dev          # Stdio with auto-reload
npm run dev:http     # HTTP/SSE with auto-reload
```

## API Reference

> **Machine-readable tool catalog for AI agents:** [`mcp-api-list.md`](./mcp-api-list.md) — a complete, offline-loadable list of every tool with its input schema (parameter / type / required / default), MCP side-effect annotations (read-only vs. on-chain write / destructive) and HITL guidance. It is **generated from source** (`npm run gen:api-list`, see [`scripts/gen-mcp-api-list.ts`](./scripts/gen-mcp-api-list.ts)) so it never drifts from the actual tool definitions. Agents can load it to plan tool routing without connecting to the server.

### Tools (98 total)

The full, authoritative per-tool catalog — every tool's input schema, side-effect class (read-only / on-chain write / destructive) and HITL guidance — lives in [`mcp-api-list.md`](./mcp-api-list.md), **generated from source** (`npm run gen:api-list`) so it never drifts. Counts by category:

| Category | Tools | Covers |
|----------|------:|--------|
| Wallet & Network | 10 | wallet selection, signing mode (browser/agent), active wallet, network |
| Market Data | 13 | per-market & protocol APY/TVL/rates (contract query + API fallback) |
| Lending Operations | 10 | supply / borrow / repay / withdraw / collateral / approve (V1 jTokens) |
| JST Voting / Governance | 10 | proposals, vote status, WJST approve / vote / withdraw |
| Energy Rental | 9 | rental dashboard, price estimate, rent / return energy |
| sTRX Staking | 7 | sTRX dashboard & account, stake / unstake / claim / withdraw |
| WTRX Wrap / Unwrap | 2 | `wrap_trx` (TRX→WTRX 1:1) / `unwrap_trx` (WTRX→TRX 1:1) |
| JustLend V2 (Moolah) — Vaults | 6 | ERC4626 vault read + deposit / withdraw / redeem / approve |
| JustLend V2 (Moolah) — Markets | 8 | isolated markets: supply-collateral / borrow / repay / approve |
| JustLend V2 (Moolah) — Liquidation | 5 | pending liquidations, quote, liquidate, approve |
| JustLend V2 (Moolah) — Dashboard & History | 6 | portfolio, positions, dashboard & history |
| JustLend V2 (Moolah) — Mining, Rewards & Estimator | 5 | mining APY / accrual, claim, gas estimate |
| Historical Records (V1 + airdrop) — mainnet-only | 7 | transaction / vote / reward history, claimable airdrops |

Every write / d

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [justlend](https://github.com/justlend)
- **Source:** [justlend/mcp-server-justlend](https://github.com/justlend/mcp-server-justlend)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-justlend-mcp-server-justlend
- Seller: https://agentstack.voostack.com/s/justlend
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.