Liquid Backend MCP

Model Context Protocol (MCP) server for the Liquid trading platform. This package provides a stdio-based MCP server that connects to the Liquid Backend API, allowing AI assistants like Claude to interact with Liquid's trading capabilities.

Installation

npm install -g liquid-backend-mcp

Or use directly with npx:

npx liquid-backend-mcp

Usage

With Claude Desktop

Add this to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "liquid-backend": {
      "command": "npx",
      "args": [
        "-y",
        "liquid-backend-mcp",
        "--client=claude",
        "--tools=dynamic"
      ],
      "env": {
        "LIQUID_BACKEND_URL": "https://liquid-backend-dev.nj-345.workers.dev"
      }
    }
  }
}

With Python MCP Client

from mcp_client import MCPToolset, StdioServerParameters
import os

# Create MCP toolset
liquid_mcp = MCPToolset(
    connection_params=StdioServerParameters(
        command='npx',
        args=[
            "-y",  # Auto-confirm install
            "liquid-backend-mcp",
            "--client=claude",
            "--tools=dynamic"
        ],
        env={
            "LIQUID_BACKEND_URL": os.getenv("LIQUID_BACKEND_URL", "https://liquid-backend-dev.nj-345.workers.dev")
        }
    ),
    # Optional: Filter to specific tools
    # tool_filter=['get_portfolio_overview', 'buy_asset', 'search_tokens']
)

# Use the tools with JWT authentication
user_jwt = get_user_jwt()  # Get JWT from your auth system
result = await liquid_mcp.call_tool('get_portfolio_overview', {
    'jwt': user_jwt
})

# Example with additional parameters
result = await liquid_mcp.call_tool('buy_asset', {
    'jwt': user_jwt,
    'asset': 'bitcoin',
    'amount': 100
})

Command Line Options

• --client <client>: Client type (default: "claude")
• --tools <tools>: Tools configuration (default: "dynamic")
• --api-url <url>: Liquid Backend API URL (overrides env var)
• --debug: Enable debug logging

Environment Variables

• LIQUID_BACKEND_URL: API endpoint URL (default: https://liquid-backend-dev.nj-345.workers.dev)

Authentication

The MCP server uses JWT tokens for authentication. Instead of configuring a single JWT token as an environment variable, JWT tokens must be passed with each tool call. This allows the MCP server to handle requests from multiple users.

How to Pass JWT Tokens

Include the JWT token as a parameter named jwt in every tool call:

// Example tool call with JWT
{
  "name": "get_portfolio_overview",
  "arguments": {
    "jwt": "eyJhbGciOiJIUzI1NiIs..."  // Your user's JWT token
  }
}

Public Tools

Some tools don't require authentication and can be called without a JWT:

• search_tokens
• get_token_price
• get_token_price_by_address

For these tools, you can omit the jwt parameter.

Available Tools

Portfolio Management

• get_portfolio_overview: Get comprehensive portfolio overview
• get_portfolio_positions: Get current positions with values
• get_portfolio_performance: Get performance metrics
• get_portfolio_history: Get transaction history

Trading

• buy_asset: Execute buy orders
• sell_asset: Execute sell orders
• get_trade_estimate: Get trade cost estimates
• get_trade_history: Get trading history

Market Data

• search_tokens: Search for crypto tokens
• get_token_price: Get token prices
• get_token_price_by_address: Get price by contract address

User Management

• get_user_profile: Get user profile information
• get_user_wallet: Get wallet information

Example Usage

Authenticated Tool Call

# Get portfolio overview for a specific user
result = await liquid_mcp.call_tool('get_portfolio_overview', {
    'jwt': user_jwt_token
})

# Execute a trade
result = await liquid_mcp.call_tool('buy_asset', {
    'jwt': user_jwt_token,
    'symbol': 'BTC',
    'amount': 0.01
})

Public Tool Call

# Search tokens (no authentication required)
result = await liquid_mcp.call_tool('search_tokens', {
    'query': 'ethereum'
})

Development

Building from Source

git clone https://github.com/liquid-labs/liquid-backend.git
cd liquid-backend/mcp-package
npm install
npm run build

Testing Locally

# Run directly with TypeScript
npm run dev -- --debug

# Or build and run
npm run build
node dist/cli.js --debug

Publishing

npm run build
npm publish

License

MIT

Support

For issues and feature requests, please visit: https://github.com/liquid-labs/liquid-backend/issues