🌐 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

🚀 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:

Always specify the wallet address for user-specific operations
Set appropriate amounts in TLOS or token units
Monitor gas prices before large transactions
Check balances before attempting swaps or stakes
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

Built by Tairon.ai team with help from Claude

Name		Name	Last commit message	Last commit date
src		src
test		test
utils		utils
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
jest.config.js		jest.config.js
jest.integration.config.js		jest.integration.config.js
nest-cli.json		nest-cli.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
tsconfig.mcp.json		tsconfig.mcp.json

Latest commit

History

Folders and files

Repository files navigation