<div align="center">

🌐 Telos Network MCP Server v0.1

Production-ready Model Context Protocol (MCP) server for Telos blockchain DeFi operations and analytics

Features • Quick Start • API • Tools • Examples • Prompts • Security

</div>

---

🚀 Features

🎯 Complete DeFi Ecosystem Integration

• Full Swapsicle V2 DEX support with concentrated liquidity
• sTLOS liquid staking protocol with 13% APY
• Real-time TVL and APY tracking via DefiLlama
• Live trading data and pool analytics from DexScreener
• Smart deposit automation with optimal routing
• Cross-chain bridging via LayerZero

🧠 Intelligent Token Management

• Support for 45+ tokens including TLOS, stablecoins, and ecosystem tokens
• Automatic token detection and balance management
• Smart routing through multiple DEX aggregators
• Real-time price feeds from Teloscan API
• Slippage protection and MEV resistance

🤖 MCP Protocol Implementation

• 34+ specialized tools for blockchain automation
• Compatible with Claude Desktop and AI assistants
• HTTP, SSE, and stdio transport support
• Real-time transaction execution with automatic signing
• Comprehensive error handling and retry logic
• WebSocket support for live blockchain events

🏛️ Enterprise-Ready Architecture

• Built with NestJS v11 for scalability
• TypeScript 5.7 for type safety
• Modular service architecture
• 80%+ test coverage requirement
• Docker multi-stage builds
• Comprehensive logging and monitoring

---

📦 Quick Start

✅ Prerequisites

# Required
Node.js >= 18.0.0
pnpm >= 8.0.0 (REQUIRED - do not use npm or yarn)

# Optional
Docker & Docker Compose (for containerized deployment)
Private key for transaction execution

📥 Installation

# Clone the repository
git clone https://github.com/Tairon-ai/telos-mcp.git
cd telos-mcp

# Install dependencies (MUST use pnpm)
pnpm install

# Configure environment
cp .env.example .env
# Edit .env with your configuration

# Start the server
pnpm run start

# Development mode with hot reload
pnpm run start:dev

# MCP stdio server for Claude Desktop
pnpm run start:mcp

🐳 Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

🤖 Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "telos-mcp": {
      "command": "node",
      "args": ["/path/to/telos-mcp/dist/stdio/mcp-server.js"],
      "env": {
        "RPC_URL": "https://rpc.telos.net/evm",
        "PRIVATE_KEY": "your_private_key_without_0x"
      }
    }
  }
}

---

🛠 Available Tools

🏦 DeFi Protocol Operations

Tool	Description	Parameters
telos_stake	Stake TLOS for sTLOS (13% APY)	amount, address
telos_unstake	Unstake sTLOS back to TLOS	amount, address
swapsicle_swap	Execute token swap on Swapsicle	tokenIn, tokenOut, amount, address
swapsicle_quote	Get swap quote	tokenIn, tokenOut, amount
swapsicle_pools	Get liquidity pool information	-
smart_deposit_auto	Auto-convert and stake	inputToken, amount, address

💱 Token Operations

Tool	Description	Parameters
get_balance	Get TLOS or token balance	token, address
get_address_balances	Get all token balances	address
telos_wrap	Wrap TLOS to WTLOS	amount, address
telos_unwrap	Unwrap WTLOS to TLOS	amount, address
telos_token_price	Get token price	token
telos_tokens_list	List all supported tokens	-

📊 Analytics & Data

Tool	Description	Parameters
telos_top_stable_yields	Top stable coin yields	limit
telos_biggest_lps	Largest liquidity pools by TVL	limit
telos_realtime_pairs	Real-time trading pairs	token
telos_trending_tokens	Trending tokens by volume	limit
telos_tvl_rankings	Protocol TVL rankings	-
telos_protocol_details	Protocol information	protocol
telos_historical_tvl	Historical TVL data	protocol, days

🔍 Blockchain Utilities

Tool	Description	Parameters
get_gas_price	Get current gas price	-
telos_top_native_holders	Top TLOS holders	limit
telos_top_token_holders	Top holders for any token	token, limit
telos_token_search	Search tokens on DexScreener	query
health_check	Server health status	-

---

🔗 API Endpoints

🌐 Core Endpoints

GET  /           # Server status and info
GET  /health     # Health check
GET  /mcp        # MCP server information
POST /mcp        # MCP protocol endpoint
GET  /mcp/tools  # List available tools
GET  /info       # Server capabilities

📡 WebSocket/SSE Support

GET /sse         # Server-Sent Events for real-time updates
GET /stdio       # Stdio process status
POST /stdio      # Send request to stdio MCP server

---

💡 Examples

💰 Stake TLOS for sTLOS

// Stake 100 TLOS to earn 13% APY
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "telos_stake",
    "arguments": {
      "amount": "100",
      "address": "0x..."
    }
  },
  "id": 1
}

🔄 Smart Deposit with Auto-Conversion

// Automatically convert USDC to TLOS and stake
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "smart_deposit_auto",
    "arguments": {
      "inputToken": "USDC",
      "amount": "1000",
      "address": "0x..."
    }
  },
  "id": 1
}

📊 Get Best Swap Quote

// Get quote for swapping 1000 TLOS to USDC
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "swapsicle_quote",
    "arguments": {
      "tokenIn": "TLOS",
      "tokenOut": "USDC",
      "amount": "1000"
    }
  },
  "id": 1
}

🏊 Get Top Yield Opportunities

// Get top 5 stable coin yield opportunities
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "telos_top_stable_yields",
    "arguments": {
      "limit": 5
    }
  },
  "id": 1
}

---

🤖 Prompts

💬 Example Prompts for Claude, ChatGPT, or Other AI Assistants

These prompts demonstrate how to interact with the MCP server through natural language when integrated with AI assistants:

💼 Portfolio Management

"Check my TLOS balance and all token holdings at address 0x..."

"Show me the value of my portfolio in USD at 0x..."

"What's my sTLOS staking position and current rewards?"

"Calculate my total DeFi positions across all Telos protocols"

🏦 Staking Operations

"I want to stake 500 TLOS to earn yield. My address is 0x..."

"Help me unstake 200 sTLOS back to TLOS"

"What's the current APY for sTLOS staking?"

"Show me my staking rewards and when I can claim them"

"Calculate how much I'll earn staking 1000 TLOS for 30 days"

🔄 Token Swapping

"Find the best route to swap 1000 TLOS to USDC on Swapsicle"

"I have 500 USDT and want to convert it to TLOS with minimal slippage"

"Execute a swap of 2 ETH to USDC with maximum 1% slippage"

"Compare swap rates for 1000 TLOS to USDC across all DEXes"

🚀 Smart Deposits

"I have 1000 USDC and want to automatically convert and stake for best yield"

"Help me deposit and stake 500 USDT using smart deposit"

"Auto-convert my 2 ETH to TLOS and stake it all"

"What's the optimal deposit strategy for 5000 USDC?"

📊 DeFi Analytics

"Show me the top 10 liquidity pools on Telos by TVL"

"What are the best stable coin yield opportunities right now?"

"Find trending tokens on Telos with highest 24h volume"

"Show me real-time trading data for TLOS/USDC pair"

"What's the total TVL across all Telos DeFi protocols?"

🔍 Token Information

"Get the current price of TLOS in USD"

"Show me the top 20 TLOS holders"

"Who are the biggest holders of ZAPPY token?"

"List all supported tokens with their current prices"

"Search for 'CHARM' token and show me its liquidity pools"

📈 Yield Strategies

"What are the top 5 stable yields on Telos?"

"Show me the best APY opportunities for USDC"

"Compare yields between different stablecoin pools"

"Find the highest yielding pools with over $100k TVL"

"Calculate my potential returns for providing liquidity to TLOS/USDC"

⛽ Transaction Management

"Check current gas prices on Telos network"

"Estimate transaction cost for staking 1000 TLOS"

"Show me my last 10 transactions"

"What's the optimal gas price for a fast transaction?"

🔧 Integration Tips for AI Assistants

When using these prompts with the MCP server:

1. Always specify the wallet address for user-specific operations
2. Set appropriate amounts in TLOS or token units
3. Monitor gas prices before large transactions
4. Check balances before attempting swaps or stakes
5. Use quotes first before executing actual swaps

🗺️ Natural Language to Tool Mapping

User Intent	MCP Tool to Use
"Check my balance"	get_address_balances
"Stake TLOS"	telos_stake
"Unstake sTLOS"	telos_unstake
"Swap tokens"	swapsicle_swap
"Get swap quote"	swapsicle_quote
"Auto deposit and stake"	smart_deposit_auto
"View top yields"	telos_top_stable_yields
"Find liquidity pools"	telos_biggest_lps
"Get token price"	telos_token_price
"Search tokens"	telos_token_search

---

🧪 Testing

🧪 Run Tests

# Run all tests
pnpm test

# Run with coverage
pnpm test:cov

# Run specific test suites
pnpm test:unit
pnpm test:integration
pnpm test:e2e

# Test specific modules
pnpm test:blockchain
pnpm test:staking
pnpm test:swaps

🔍 API Testing with cURL

# Check server health
curl http://localhost:8080/health

# Get MCP server info
curl http://localhost:8080/mcp

# List all available tools
curl http://localhost:8080/mcp/tools

# Execute a tool
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_balance",
      "arguments": {
        "token": "TLOS",
        "address": "0x..."
      }
    },
    "id": 1
  }'

---

🔒 Security

🔐 Best Practices

• Private Key Management: Never commit private keys. Use environment variables
• Transaction Simulation: Test with AUTO_EXECUTE=false first
• Slippage Protection: Set appropriate limits (typically 0.5-2%)
• Gas Management: Monitor gas prices and set reasonable limits
• Access Control: Implement authentication for production
• Monitoring: Use Teloscan to track all transactions

🛡️ Security Features

• Automatic gas estimation with buffer
• Transaction simulation before execution
• Slippage protection on all swaps
• Input validation and sanitization
• Rate limiting (configurable)
• Comprehensive error handling

---

📊 Supported Networks & Tokens

🌐 Network

• Telos EVM Mainnet (Chain ID: 40)
• RPC: https://rpc.telos.net/evm
• Explorer: Teloscan

🪙 Supported Tokens (45+)

Native & Staking

• TLOS, WTLOS, sTLOS

Stablecoins

• USDC, USDT, USDD, LUSD, FRAX

Major Tokens

• ETH, WETH, BTC, WBTC, BNB

Ecosystem Tokens

• CHARM, ZAPPY, DOUGE, SWAP, IMX, TSWAPS, LVTX, VEX

DeFi Tokens

• AAVE, LINK, UNI, SUSHI, CRV, BAL

📜 Key Contracts

• Swapsicle V2 Router: 0x93395129bd3fcf49d95730D3C2737c17990fF328
• sTLOS Staking: 0xB4B01216a5Bc8F1C8A33CD990A1239030E60C905
• Omnidex Router: 0xF9678db1CE83f6f51E5df348E2Cc842Ca51EfEc1

---

🚀 Deployment

🏭 Production Deployment

# Build for production
pnpm run build

# Start production server
pnpm run start:prod

# Build MCP server
pnpm run build:mcp

# With PM2
pm2 start dist/main.js --name telos-mcp

# With Docker
docker build -t telos-mcp .
docker run -d -p 8080:8080 --env-file .env telos-mcp

🔑 Environment Variables

# Required
PORT=8080
RPC_URL=https://rpc.telos.net/evm
CHAIN_ID=40
PRIVATE_KEY=your_private_key_without_0x
TELOS_API_URL=https://api.teloscan.io

# Optional
LOG_LEVEL=info
AUTO_EXECUTE=true
TRANSACTION_MODE=interactive
RATE_LIMIT_TTL=60
RATE_LIMIT_MAX=100

---

📈 Performance

• Response Time: <50ms for read operations
• Transaction Speed: ~0.5s on Telos network
• Throughput: 1000+ requests per second
• Uptime: 99.9% availability target
• Gas Optimization: Ultra-low fees on Telos
• Caching: 1-minute cache for price data

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

# Fork and clone
git fork https://github.com/Tairon-ai/telos-mcp
git clone https://github.com/Tairon-ai/telos-mcp

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
pnpm test
pnpm run lint

# Commit and push
git commit -m 'feat: add amazing feature'
git push origin feature/amazing-feature

# Open Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Telos Network - High-performance EVM blockchain
• Swapsicle - Leading DEX on Telos
• DefiLlama - DeFi TVL aggregator
• DexScreener - Real-time DEX analytics
• Model Context Protocol - AI integration standard
• NestJS - Progressive Node.js framework

---

<div align="center">

Built by Tairon.ai team with help from Claude

</div>