# Sun Mcp Server

> sun mcp server

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

## Install

```sh
agentstack add mcp-sun-protocol-sun-mcp-server
```

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

## About

# SUN MCP Server

An MCP server for AI-driven DeFi operations on the TRON network through the SUN.IO / SUNSWAP ecosystem.

## Contents

- [Overview](#overview)
- [Quick Start](#quick-start)
  - [Official Hosted MCP (Read-Only)](#official-hosted-mcp-read-only)
  - [Local Hosted MCP](#local-hosted-mcp)
    - [Configuration](#configuration)
      - [Wallet Configuration](#wallet-configuration)
      - [Network Configuration](#network-configuration)
    - [Verify](#verify)
  - [Example Prompts](#example-prompts)
- [Client Integration Guide](#client-integration-guide)
  - [Claude Desktop](#claude-desktop)
  - [Cursor](#cursor)
  - [Production HTTP Deployment](#production-http-deployment)
- [API & Tools Reference](#api--tools-reference)
  - [Supported SUN.IO API Domains](#supported-sunio-api-domains)
  - [Wallet & Portfolio](#wallet--portfolio)
  - [Price & Quote](#price--quote)
  - [Swap](#swap)
  - [V2 Liquidity](#v2-liquidity)
  - [V3 Liquidity](#v3-liquidity)
  - [V4 Liquidity](#v4-liquidity)
  - [Generic Contract](#generic-contract)
  - [Auto-Compute Features](#auto-compute-features)
- [Troubleshooting](#troubleshooting)
- [Security Considerations](#security-considerations)

## Overview

Connect any AI client to the TRON DeFi ecosystem through a single MCP endpoint. With `@sun-protocol/sun-mcp-server`, your AI agent can:

- **Query** — token prices, pool stats, liquidity positions, farming rewards, protocol metrics
- **Quote** — swap routes and price impact across SUNSwap V2, V3, and V4
- **Execute** — token swaps, liquidity add/remove, position management (wallet required)
- **Contract** — read from or write to arbitrary TRON smart contracts

The server supports **stdio** (local) and **Streamable HTTP** (remote) transports. Without a wallet configured, it runs in read-only mode — safe for exploration and data queries.

## Quick Start

### Official Hosted MCP (Read-Only)

The fastest way to try SUN MCP Server — no installation, no configuration. BankOfAI hosts a public read-only instance.

**Point your client to the official endpoint:**

```bash
claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp
```

This gives you access to all read-only tools: token prices, pool data, positions, quoting, and more. No wallet is configured on the hosted instance, so write operations (swaps, liquidity) are not available.

**curl example** — call the `getPrice` tool via MCP JSON-RPC:

```bash
curl -X POST https://sun-mcp-server.bankofai.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "getPrice",
      "arguments": {
        "tokenAddress": "TKkeiboTkxXKJpbmVFbv4a8ov5rAfRDMf9"
      }
    }
  }'
```

Response (SSE format):

```
event: message
data: {
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"msg\":\"SUCCESS\",\"code\":0,\"data\":{\"TKkeiboTkxXKJpbmVFbv4a8ov5rAfRDMf9\":{\"quote\":{\"USD\":{\"price\":\"37.513242926312\"}}}},\"status\":{\"error_code\":0}}"
      }
    ]
  },
  "jsonrpc": "2.0",
  "id": 1
}
```

> No local installation needed. Works with any MCP client that supports Streamable HTTP.

### Local Hosted MCP

Run the server locally with full capabilities — including write operations if you configure a wallet.

**Install:**

```bash
npm install -g @sun-protocol/sun-mcp-server
```

### Configuration

#### Wallet Configuration

Without a wallet, the server works in **read-only mode** — you can query prices, pools, positions, and more.

Wallets are managed through [`agent-wallet`](https://github.com/BofAI/agent-wallet?tab=readme-ov-file#quick-start) file-backed configuration. Install and configure `agent-wallet` first. This repository no longer reads or maps legacy `TRON_PRIVATE_KEY`, `TRON_MNEMONIC`, or `TRON_MNEMONIC_ACCOUNT_INDEX` wallet variables.

> **Note**
> See [`agent-wallet`](https://github.com/BofAI/agent-wallet?tab=readme-ov-file#quick-start) for wallet file formats, local setup, and the full set of SDK-supported `AGENT_WALLET_*` options.

#### Network Configuration

- `TRON_NETWORK` — optional network override, defaults to `mainnet`
- `TRON_GRID_API_KEY` — optional TronGrid API key for higher-rate mainnet access
- `TRON_RPC_URL` — optional custom TRON RPC endpoint

Example:

```bash
export TRON_NETWORK=mainnet
export TRON_GRID_API_KEY=""
export TRON_RPC_URL=https://your-tron-rpc.example
```

**stdio** — the MCP client spawns and manages the server process automatically. No manual server management needed.

```bash
# Read-only (no wallet)
claude mcp add sun-mcp-server sun-mcp-server

# With wallet and runtime settings
claude mcp add sun-mcp-server sun-mcp-server \
  -e AGENT_WALLET_PRIVATE_KEY=your_private_key
```

Environment variables passed via `-e` are injected into the server process. Claude starts the server when it needs SUN.IO tools, and stops it when done.

> You can also skip the global install and use `npx`:
> ```bash
> claude mcp add sun-mcp-server -- npx -y @sun-protocol/sun-mcp-server
> ```

**Streamable HTTP** — run a persistent HTTP server, useful for sharing one endpoint across a team or deploying in Docker / Kubernetes.

```bash
# Start the server
sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp

# Register it with your MCP client
claude mcp add --transport http sun-mcp-server http://127.0.0.1:8080/mcp
```

> For external access (e.g. from other machines or containers), bind to `0.0.0.0` instead of `127.0.0.1`.

### Verify

Confirm the server is registered:

```bash
claude mcp list
```

You should see `sun-mcp-server` in the output. Now just chat with Claude — see [Example Prompts](#example-prompts) below.

### Example Prompts

**Market data (read-only, no wallet needed):**

- "Get the current price of SUN and JST on TRON."
- "List the most liquid SUNSwap pools for USDT."
- "Show my V3 and V4 positions for wallet `T...`."

**Quoting (read-only):**

- "Quote a swap from 100 USDT to TRX on SUNSwap."
- "Quote the best exact-input route for 500 USDT to SUN."

**Wallet & execution (requires wallet):**

- "Get balances for my active wallet on TRON."
- "Swap 100 USDT to TRX on SUNSwap."
- "Mint a V3 position between these two ticks."
- "Increase liquidity for this V4 position."

**Contract interaction:**

- "Read the `slot0` state from this SUNSwap pool contract."

## Client Integration Guide

The [Quick Start](#quick-start) examples use Claude Code. If you use a different MCP client, follow the patterns below.

### Claude Desktop

Add to your MCP configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

**stdio (recommended):**

```json
{
  "mcpServers": {
    "sun-mcp-server": {
      "command": "sun-mcp-server",
      "args": [],
      "env": {
        "TRON_NETWORK": "mainnet"
      }
    }
  }
}
```

**Remote HTTP** (if using a hosted or self-hosted HTTP endpoint):

```json
{
  "mcpServers": {
    "sun-mcp-server": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project root:

**stdio:**

```json
{
  "mcpServers": {
    "sun-mcp-server": {
      "command": "sun-mcp-server",
      "args": [],
      "env": {
        "TRON_NETWORK": "mainnet"
      }
    }
  }
}
```

**Remote HTTP:**

```json
{
  "mcpServers": {
    "sun-mcp-server": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}
```

### Production HTTP Deployment

If you are deploying the server for shared or production use, consider adding:

- TLS termination via reverse proxy (Nginx, Caddy, Cloudflare)
- Authentication at the proxy or gateway layer
- Request logging and rate limiting
- Secret injection through your deployment platform instead of `.env` files

## API & Tools Reference

| Category | Tools | Wallet Required | Description |
|----------|-------|:---:|-------------|
| [SUN.IO API](#supported-sunio-api-domains) | Dynamic (from OpenAPI spec) | No | Protocol, token, pool, pair, price, position, farm data |
| [Wallet & Portfolio](#wallet--portfolio) | `get_wallet_address`, `get_balances` | Yes | Wallet address and TRX/TRC20 balances |
| [Price & Quote](#price--quote) | `get_token_price`, `quote_exact_input` | No | Spot prices and smart-router quoting |
| [Swap](#swap) | `swap`, `swap_exact_input` | Quote: No / Execute: Yes | Route discovery and token swaps |
| [V2 Liquidity](#v2-liquidity) | `v2_add_liquidity`, `v2_remove_liquidity` | Yes | Classic LP add/remove |
| [V3 Liquidity](#v3-liquidity) | `v3_mint_position`, `v3_increase_liquidity`, `v3_decrease_liquidity`, `v3_collect` | Yes | Concentrated liquidity positions |
| [V4 Liquidity](#v4-liquidity) | `v4_mint_position`, `v4_increase_liquidity`, `v4_decrease_liquidity`, `v4_collect` | Yes | V4 position management and fee collection |
| [Generic Contract](#generic-contract) | `read_contract`, `send_contract` | Read: No / Send: Yes | Direct TRON contract interaction |

> All custom tool names are prefixed with `sunswap_` (e.g. `sunswap_swap`, `sunswap_v3_mint_position`).

---

### Supported SUN.IO API Domains

The server dynamically generates read-only tools from the bundled SUN.IO OpenAPI spec. The default spec includes:

| Domain | Tool | Endpoint | Description |
|--------|------|----------|-------------|
| Transactions | `scanTransactions` | `GET /apiv2/transactions/scan` | Scan swap/add/withdraw activity with pagination |
| Tokens | `getTokens` | `GET /apiv2/tokens` | Fetch tokens by address and protocol |
| | `searchTokens` | `GET /apiv2/tokens/search` | Fuzzy token search by keyword |
| Protocols | `getProtocol` | `GET /apiv2/protocols` | Protocol snapshot data |
| | `getVolHistory` | `GET /apiv2/protocols/history/vol` | Protocol volume history |
| | `getLiqHistory` | `GET /apiv2/protocols/history/liq` | Protocol liquidity history |
| | `getUsersCountHistory` | `GET /apiv2/protocols/history/usersCount` | Protocol users history |
| | `getTransactionsHistory` | `GET /apiv2/protocols/history/transactions` | Protocol transaction count history |
| | `getPoolsCountHistory` | `GET /apiv2/protocols/history/poolsCount` | Protocol pool count history |
| Prices | `getPrice` | `GET /apiv2/price` | Token price by address |
| Positions | `getUserPositions` | `GET /apiv2/positions/user` | User liquidity positions |
| | `getPoolUserPositionTick` | `GET /apiv2/positions/tick` | Pool tick-level position details |
| Pools | `getPools` | `GET /apiv2/pools` | Fetch pools by address, token, or protocol |
| | `searchPools` | `GET /apiv2/pools/search` | Pool search |
| | `searchCountPools` | `GET /apiv2/pools/search/count` | Pool search count |
| | `getTopApyPoolList` | `GET /apiv2/pools/top_apy_list` | Top APY pools (paginated) |
| | `getPoolHooks` | `GET /apiv2/pools/hooks` | Pool hooks list |
| | `getPoolVolHistory` | `GET /apiv2/pools/history/vol` | Pool volume history |
| | `getPoolLiqHistory` | `GET /apiv2/pools/history/liq` | Pool liquidity history |
| Pairs | `getPairsFromEntity` | `GET /apiv2/pairs` | Token pair entity query |
| Farms | `getFarms` | `GET /apiv2/farms` | Farming pool list |
| | `getFarmTransactions` | `GET /apiv2/farms/transactions` | Farm transaction scanning |
| | `getFarmPositions` | `GET /apiv2/farms/positions/user` | User farming positions |

> The exact set of tools depends on the loaded OpenAPI spec and any configured whitelist/blacklist filters.

### Wallet & Portfolio

Key tools:

- `sunswap_get_wallet_address` — returns the active TRON wallet address
- `sunswap_get_balances` — returns TRX and TRC20 token balances for the active wallet

These tools are read-only and require a configured wallet source.

### Price & Quote

Key tools:

- `sunswap_get_token_price` — spot price lookup via SUN.IO API
- `sunswap_quote_exact_input` — smart-router exact-input quoting across SUNSwap V2, V3, and V4 pools

Both tools are read-only and do not require a wallet.

### Swap

Key tools:

- `sunswap_swap` — higher-level swap that handles route computation and execution in one call
- `sunswap_swap_exact_input` — execute an exact-input swap via the smart router

Swap tools can operate in:

- Read-only quote mode without a wallet
- Execution mode with a configured wallet source

### V2 Liquidity

Key tools:

- `sunswap_v2_add_liquidity`
- `sunswap_v2_remove_liquidity`

Use these for classic LP flows on SUNSwap V2-style pools.

### V3 Liquidity

Key tools:

- `sunswap_v3_mint_position`
- `sunswap_v3_increase_liquidity`
- `sunswap_v3_decrease_liquidity`
- `sunswap_v3_collect`

These tools support concentrated liquidity workflows for SUNSwap V3-style positions.

### V4 Liquidity

Key tools:

- `sunswap_v4_mint_position`
- `sunswap_v4_increase_liquidity`
- `sunswap_v4_decrease_liquidity`
- `sunswap_v4_collect`

These tools support SUNSwap V4-style position management and fee collection.

### Generic Contract

Key tools:

- `sunswap_read_contract`
- `sunswap_send_contract`

Use these when you need direct TRON contract interaction outside the higher-level abstractions.

### Auto-Compute Features

The higher-level SUNSwap tools automatically compute or fill in parameters so that clients can call them with minimal input. Below is what each category handles:

**All write tools:**

- `recipient` defaults to the active wallet address
- `deadline` defaults to 30 minutes from now
- Transactions are built, signed, and broadcast in a single call

**V3 Mint (`sunswap_v3_mint_position`):**

- If tick range is omitted, defaults to ±50 × tickSpacing around the current price
- Supports single-sided input — provide only `amount0` or `amount1`
- Slippage tolerance defaults to 95%

**V4 Mint (`sunswap_v4_mint_position`):**

- If tick range is omitted, defaults to ±100 × tickSpacing around the current price
- Slippage tolerance defaults to 5%

**Swap tools:**

- `sunswap_swap` handles route discovery, quoting, and execution as one operation
- `sunswap_swap_exact_input` accepts a pre-computed route or finds the best one automatically

This reduces client-side orchestration and keeps the MCP interface simpler than raw contract calls.

## Troubleshooting

**Write tools fail with "no wallet configured"**
You are running in read-only mode. Set exactly one wallet source (`AGENT_WALLET_PRIVATE_KEY`, `AGENT_WALLET_MNEMONIC`, or `AGENT_WALLET_PASSWORD`) and restart the server.

**Server rejects startup with "conflicting wallet modes"**
More than one wallet source is set. Remove the extras so that only one of the three wallet environment variable groups is present.

**Too many tools — LLM context or token limit exceeded**
Use `--whitelist` / `--blacklist` (or the `MCP_WHITELIST_OPERATIONS` / `MCP_BLACKLIST_OPERATIONS` environment variables) to limit which OpenAPI tools are exposed. For example, `--whitelist "getPools,getTokenPrice,GET:/apiv2/tokens/*"` keeps only the tools you need.

**API requests time out or return empty results**
Check `TRON_RPC_URL` and `TRON_GRID_API_KEY`. The default public TronGrid endpoint has rate limits. For production use, supply your own API key or a dedicated RPC endpoint.

**Connection refused on Streamable HTTP**
Verify `MCP_SERVER_HOST`, `MCP_SERVER_PORT`, and `MCP_SERVER_PATH` match what your client is connecting to. If the server binds to `127.0.0.1`, it will not be reachable from other machines — use `0.0.0.0` for external access.

## Security Considerations

- Treat `AGENT_WALLET_PRIVATE_KEY`, `AGENT_WALLET_MNEMONIC`, and `AGENT_WALLET_PASSWORD` as production secrets.
- Configure exactly one wallet source at a time. The server rejects conflicting wallet modes.
- Prefer read-only deployments when you only need market data or position inspection.
- Do not expose a write-enabled Streamable HTTP deployment directly to the public internet without authentication and transport security.
- If you use `AGENT_WALLET_PASSWORD`, keep `AGENT_WALLET_DIR` on encrypted storage where possible.
- Review any custom RPC endpo

…

## Source & license

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

- **Author:** [sun-protocol](https://github.com/sun-protocol)
- **Source:** [sun-protocol/sun-mcp-server](https://github.com/sun-protocol/sun-mcp-server)
- **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:** yes
- **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-sun-protocol-sun-mcp-server
- Seller: https://agentstack.voostack.com/s/sun-protocol
- 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%.