🌊 Liquidswap MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to Liquidswap - the leading decentralized exchange on the Aptos blockchain. This server enables AI models and applications to interact with Liquidswap's pools, tokens, and user balances through a standardized interface.

🚀 Features

• Real-time Data Access: Get live information about tokens, pools, and user balances
• Historical Analytics: Access historical APR and TVL data for in-depth analysis
• User Balance Tracking: Query token balances for any Aptos address
• MCP Standard Compliance: Seamlessly integrates with MCP-compatible AI tools and applications
• TypeScript Support: Fully typed for better development experience

🛠️ Available Tools

1. Get Tokens (get_tokens)

Retrieves all tokens registered on Liquidswap.

Parameters: None
Returns: Complete list of registered tokens with metadata (name, symbol, decimals, logo, etc.)

2. Get Pools (get_pools)

Fetches all liquidity pools available on Liquidswap.

Parameters: None
Returns: List of all registered pools including concentrated liquidity pools

3. Get User Balances (get_balances_by_address)

Queries token balances for a specific Aptos address.

Parameters:

• address (string): Aptos address to query balances for

Returns: Token balances with enriched metadata including LP token details

4. Get Historical APRs (get_pools_historical_aprs)

Retrieves historical Annual Percentage Rate (APR) data for all pools.

Parameters:

• daysAgo (number): Number of days back to fetch data (max: 365 days)

Returns: Historical APR data for all pools within the specified timeframe

5. Get Historical TVLs (get_pools_historical_tvls)

Fetches historical Total Value Locked (TVL) data for all pools.

Parameters:

• daysAgo (number): Number of days back to fetch data (max: 365 days)

Returns: Historical TVL data for all pools within the specified timeframe

📦 Installation

Prerequisites

• Node.js (v18 or higher)
• Yarn package manager
• Aptos API key (for balance queries)

Setup

1. Clone the repository:

git clone https://gitlab.mind-dev.com/ai-lab/liquidswap-mcp.git
cd liquidswap-mcp

2. Install dependencies:

yarn install

3. Configure environment variables: Create a .env file in the root directory:

# Required for user balance queries
APTOS_API_KEY=your_aptos_api_key_here

# Optional: Custom Liquidswap API URL (defaults to https://api.liquidswap.com)
BE_URL=https://api.liquidswap.com

# Optional: SSE port (defaults to 3001)
SSE_PORT=3000

4. Build the project:

yarn build

5. Start the server:

yarn start

⚙️ Configuration

MCP Client Configuration

To use this server with an MCP client, add the following configuration to your MCP settings:

{
  "mcpServers": {
    "liquidswap-mcp": {
      "command": "node",
      "args": ["/path/to/liquidswap-mcp/build/index.js"],
      "env": {
        "SSE_PORT": "3000"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Replace /path/to/liquidswap-mcp/build/index.js with the actual path to your built server.

Environment Variables

Variable	Description	Required	Default
APTOS_API_KEY	Aptos Labs API key for blockchain queries	Yes (for balance queries)	-
BE_URL	Liquidswap backend API URL	No	https://api.liquidswap.com
SSE_PORT	Server-Sent Events port for MCP transport	No	3001

🔧 Development

Available Scripts

# Build the project
yarn build

# Start the server
yarn start

# Run linting
yarn lint

# Fix linting issues
yarn lint:fix

# Format code
yarn format

# Development with auto-reload
yarn dev  # If available

Project Structure

src/
├── core/           # Core Liquidswap API integration
├── tools/          # MCP tool implementations
│   ├── get-tokens/
│   ├── get-pools/
│   ├── get-balances-by-address/
│   ├── get-pools-historical-aprs/
│   └── get-pools-historical-tvls/
├── resources/      # MCP resources
├── transports/     # MCP transport layer
└── types/          # TypeScript type definitions

🌐 API Integration

This server integrates with:

• Liquidswap API (https://api.liquidswap.com) - For pools, tokens, and analytics data
• Aptos GraphQL API (https://api.mainnet.aptoslabs.com/v1/graphql) - For user balance queries

🤝 Usage Examples

Once configured with an MCP client, you can use natural language to interact with Liquidswap:

• "Show me all available tokens on Liquidswap"
• "What are the current liquidity pools?"
• "Get the token balances for address 0x123..."
• "Show me the historical APR data for the last 30 days"
• "What was the TVL trend over the past week?"

🔒 Security & Privacy

• API keys are handled securely through environment variables
• No sensitive data is logged or stored
• All requests are made directly to official Aptos and Liquidswap APIs
• The server operates in read-only mode with no transaction capabilities

📄 License

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

👨‍💻 Author

odiinnn

🔗 Related Links

• Liquidswap Website
• Aptos Blockchain
• Model Context Protocol
• Aptos Labs API

---

Built with ❤️ for the Aptos ecosystem