Saros MCP Server

Model Context Protocol (MCP) Server for Saros DeFi - Exposes Saros SDK functionality as AI-accessible tools

Overview

This project implements a Model Context Protocol (MCP) server that wraps the Saros DeFi SDK, enabling AI agents, bots, and dashboards to interact with Saros liquidity pools, farms, and analytics through natural language or simple tool calls.

Features

Core MCP Tools

get_lp_positions - Retrieve all liquidity pool positions for a wallet
simulate_rebalance - Simulate LP rebalancing based on IL threshold
portfolio_analytics - Comprehensive portfolio metrics and risk assessment
get_farm_positions - View farming positions and claimable rewards
swap_quote - Get swap quotes with price impact and slippage

Demo Clients

Test Client - Command-line testing tool
Telegram Bot - Interactive bot for portfolio management

Quick Start

Installation

cd saros-mcp-server
npm install

Running the Server

# Start the MCP server
npm start

# Development mode with auto-reload
npm run dev

Testing

# Run the test client
npm test

Usage Examples

Using with Claude Desktop

Add to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "saros": {
      "command": "node",
      "args": ["/path/to/saros-mcp-server/src/index.js"]
    }
  }
}

Then in Claude:

"Show me my LP positions for wallet HqB8Rf76fAwmd4qZpL81yB2SSLFzEgdoPwpWAUJ31ont"

"Analyze my portfolio for wallet HqB8Rf76fAwmd4qZpL81yB2SSLFzEgdoPwpWAUJ31ont"

"Get me a swap quote for 100 tokens from C98A4nkJXhpVZNAZdHUA95RpTF3T4whtQubL3YobiUX9 to EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v in pool 2wUvdZA8ZsY714Y5wUL9fkFmupJGGwzui2N74zqJWgty"

Real Working Example:

Wallet with actual LP positions: HqB8Rf76fAwmd4qZpL81yB2SSLFzEgdoPwpWAUJ31ont (5 active positions)

Known Saros Pools:

C98/USDC Pool: 2wUvdZA8ZsY714Y5wUL9fkFmupJGGwzui2N74zqJWgty

Using with the Telegram Bot

Create a bot via @BotFather
Copy your bot token
Set environment variable:

export BOT_TOKEN="your_telegram_bot_token"

Run the bot:

node examples/telegram-bot.js

Chat with your bot:

/start
/wallet 5UrM9csUEDBeBqMZTuuZyHRNhbRW4vQ1MgKJDrKU1U2v
/positions
/rebalance 5
/analytics

Programmatic Usage

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["src/index.js"],
});

const client = new Client({
  name: "my-client",
  version: "1.0.0",
}, {
  capabilities: {},
});

await client.connect(transport);

// Call tools
const result = await client.callTool({
  name: "get_lp_positions",
  arguments: { wallet: "5UrM9csUEDBeBqMZTuuZyHRNhbRW4vQ1MgKJDrKU1U2v" },
});

console.log(result.content[0].text);

Project Structure

saros-mcp-server/
├── src/
│   ├── index.js                 # Main MCP server
│   ├── services/
│   │   ├── pool-service.js      # LP pool operations
│   │   ├── farm-service.js      # Farming operations
│   │   └── analytics-service.js # Analytics & IL calculations
│   └── tools/
│       ├── get-lp-positions.js
│       ├── simulate-rebalance.js
│       ├── portfolio-analytics.js
│       ├── get-farm-positions.js
│       └── swap-quote.js
├── examples/
│   ├── test-client.js           # Test client
│   └── telegram-bot.js          # Telegram bot demo
├── package.json
└── README.md

API Reference

get_lp_positions

Get all liquidity pool positions for a wallet.

Input:

{
  "wallet": "string (Solana address)"
}

Output:

Found 2 LP position(s) for wallet: 5UrM9c...

Position 1:
- Pool: 2wUvdZ...
- LP Balance: 150.5
- Token 0: C98A4n...
- Token 1: EPjFWd...

simulate_rebalance

Simulate rebalancing strategy based on impermanent loss threshold.

Input:

{
  "wallet": "string",
  "threshold": "number (0-100)"
}

Output:

Rebalance Simulation for 5UrM9c...

IL Threshold: 5%
Positions Analyzed: 2
Recommendations: 1

1. Pool: 2wUvdZ...
   - Current IL: 6.25%
   - Severity: medium
   - Action: Consider withdrawing - high IL detected

portfolio_analytics

Get comprehensive portfolio analytics.

Input:

{
  "wallet": "string"
}

Output:

Portfolio Analytics for 5UrM9c...

Overview:
- Total Positions: 2
- Estimated Total Value: $1,250.00
- Average IL: 3.5%

Risk Assessment:
✅ Low Risk - Portfolio is performing well

get_farm_positions

Get all farming/staking positions.

Input:

{
  "wallet": "string"
}

Output:

Farm Positions for 5UrM9c...

Total Farms: 1

Position 1:
- Farm: FW9hgA...
- LP Token: HVUeNV...
- Staked Amount: 100.0
- Pending Rewards:
  • 50.5 C98

swap_quote

Get swap quote with price impact.

Input:

{
  "poolAddress": "string",
  "fromMint": "string",
  "toMint": "string",
  "amount": "number",
  "slippage": "number (optional, default 0.5)"
}

Output:

Swap Quote

Input:
- Pool: 2wUvdZ...
- Amount: 100

Output:
- Expected Output: 150.5
- Minimum Output: 149.75
- Price Impact: 0.15%
- Slippage Tolerance: 0.5%

Architecture

MCP Server Layer

Handles MCP protocol communication
Exposes tools via stdio transport
Routes requests to service layer

Service Layer

PoolService: LP positions, pool info, swap quotes
FarmService: Staking positions, rewards
AnalyticsService: IL calculations, portfolio metrics

SDK Integration

Uses @saros-finance/sdk for Solana/Saros interactions
Wraps SDK functions with error handling
Formats data for AI-friendly consumption

Development

Adding New Tools

Create tool handler in src/tools/:

export async function myNewTool(args, services) {
  const { param1, param2 } = args;

  // Tool logic here

  return {
    content: [{
      type: "text",
      text: "Result text"
    }]
  };
}

// In ListToolsRequestSchema handler
{
  name: "my_new_tool",
  description: "Tool description",
  inputSchema: { /* schema */ }
}

// In CallToolRequestSchema handler
case "my_new_tool":
  return await myNewTool(args, this.services);

Testing

# Test with example wallet
node examples/test-client.js

# Manual testing
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node src/index.js

Deployment

Local Deployment

npm start

Railway/Render

Create new service
Connect GitHub repo
Set build command: npm install
Set start command: npm start

Docker (Optional)

FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["npm", "start"]

Roadmap

Add DLMM-specific features (advanced orders, dynamic fees)
Implement real-time price feeds
Add transaction execution tools
Multi-wallet management
Historical performance tracking
Web dashboard UI

Contributing

Contributions welcome! Please:

Fork the repo
Create a feature branch
Commit changes
Submit a PR

License

MIT License - see LICENSE file

Hackathon Submission

Project: Saros MCP Server Category: SDK Usage & Developer Tools Hackathon: Saros $100K Hackathon

Key Innovations

First MCP server for Saros DeFi
AI-native portfolio management
Natural language DeFi interactions
Foundation for autonomous trading agents

Demo

Test Client: npm test
Telegram Bot: See examples/telegram-bot.js
Video Walkthrough: [Link TBD]

Resources

Support

GitHub Issues: Report bugs
Telegram: Community
Email: your-email@example.com

Built with ❤️ for the Saros Hackathon

Saros MCP Server

Model Context Protocol (MCP) Server for Saros DeFi - Exposes Saros SDK functionality as AI-accessible tools

Overview

Features

Core MCP Tools

get_lp_positions - Retrieve all liquidity pool positions for a wallet
simulate_rebalance - Simulate LP rebalancing based on IL threshold
portfolio_analytics - Comprehensive portfolio metrics and risk assessment
get_farm_positions - View farming positions and claimable rewards
swap_quote - Get swap quotes with price impact and slippage

Demo Clients

Test Client - Command-line testing tool
Telegram Bot - Interactive bot for portfolio management

Quick Start

Installation

cd saros-mcp-server
npm install

Running the Server

# Start the MCP server
npm start

# Development mode with auto-reload
npm run dev

Testing

# Run the test client
npm test

Usage Examples

Using with Claude Desktop

Add to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "saros": {
      "command": "node",
      "args": ["/path/to/saros-mcp-server/src/index.js"]
    }
  }
}

Then in Claude:

"Show me my LP positions for wallet HqB8Rf76fAwmd4qZpL81yB2SSLFzEgdoPwpWAUJ31ont"

"Analyze my portfolio for wallet HqB8Rf76fAwmd4qZpL81yB2SSLFzEgdoPwpWAUJ31ont"

"Get me a swap quote for 100 tokens from C98A4nkJXhpVZNAZdHUA95RpTF3T4whtQubL3YobiUX9 to EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v in pool 2wUvdZA8ZsY714Y5wUL9fkFmupJGGwzui2N74zqJWgty"

Real Working Example:

Wallet with actual LP positions: HqB8Rf76fAwmd4qZpL81yB2SSLFzEgdoPwpWAUJ31ont (5 active positions)

Known Saros Pools:

C98/USDC Pool: 2wUvdZA8ZsY714Y5wUL9fkFmupJGGwzui2N74zqJWgty

Using with the Telegram Bot

Create a bot via @BotFather
Copy your bot token
Set environment variable:

export BOT_TOKEN="your_telegram_bot_token"

Run the bot:

node examples/telegram-bot.js

Chat with your bot:

/start
/wallet 5UrM9csUEDBeBqMZTuuZyHRNhbRW4vQ1MgKJDrKU1U2v
/positions
/rebalance 5
/analytics

Programmatic Usage

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["src/index.js"],
});

const client = new Client({
  name: "my-client",
  version: "1.0.0",
}, {
  capabilities: {},
});

await client.connect(transport);

// Call tools
const result = await client.callTool({
  name: "get_lp_positions",
  arguments: { wallet: "5UrM9csUEDBeBqMZTuuZyHRNhbRW4vQ1MgKJDrKU1U2v" },
});

console.log(result.content[0].text);

Project Structure

saros-mcp-server/
├── src/
│   ├── index.js                 # Main MCP server
│   ├── services/
│   │   ├── pool-service.js      # LP pool operations
│   │   ├── farm-service.js      # Farming operations
│   │   └── analytics-service.js # Analytics & IL calculations
│   └── tools/
│       ├── get-lp-positions.js
│       ├── simulate-rebalance.js
│       ├── portfolio-analytics.js
│       ├── get-farm-positions.js
│       └── swap-quote.js
├── examples/
│   ├── test-client.js           # Test client
│   └── telegram-bot.js          # Telegram bot demo
├── package.json
└── README.md

API Reference

get_lp_positions

Get all liquidity pool positions for a wallet.

Input:

{
  "wallet": "string (Solana address)"
}

Output:

Found 2 LP position(s) for wallet: 5UrM9c...

Position 1:
- Pool: 2wUvdZ...
- LP Balance: 150.5
- Token 0: C98A4n...
- Token 1: EPjFWd...

simulate_rebalance

Simulate rebalancing strategy based on impermanent loss threshold.

Input:

{
  "wallet": "string",
  "threshold": "number (0-100)"
}

Output:

Rebalance Simulation for 5UrM9c...

IL Threshold: 5%
Positions Analyzed: 2
Recommendations: 1

1. Pool: 2wUvdZ...
   - Current IL: 6.25%
   - Severity: medium
   - Action: Consider withdrawing - high IL detected

portfolio_analytics

Get comprehensive portfolio analytics.

Input:

{
  "wallet": "string"
}

Output:

Portfolio Analytics for 5UrM9c...

Overview:
- Total Positions: 2
- Estimated Total Value: $1,250.00
- Average IL: 3.5%

Risk Assessment:
✅ Low Risk - Portfolio is performing well

get_farm_positions

Get all farming/staking positions.

Input:

{
  "wallet": "string"
}

Output:

Farm Positions for 5UrM9c...

Total Farms: 1

Position 1:
- Farm: FW9hgA...
- LP Token: HVUeNV...
- Staked Amount: 100.0
- Pending Rewards:
  • 50.5 C98

swap_quote

Get swap quote with price impact.

Input:

{
  "poolAddress": "string",
  "fromMint": "string",
  "toMint": "string",
  "amount": "number",
  "slippage": "number (optional, default 0.5)"
}

Output:

Swap Quote

Input:
- Pool: 2wUvdZ...
- Amount: 100

Output:
- Expected Output: 150.5
- Minimum Output: 149.75
- Price Impact: 0.15%
- Slippage Tolerance: 0.5%

Architecture

MCP Server Layer

Handles MCP protocol communication
Exposes tools via stdio transport
Routes requests to service layer

Service Layer

PoolService: LP positions, pool info, swap quotes
FarmService: Staking positions, rewards
AnalyticsService: IL calculations, portfolio metrics

SDK Integration

Uses @saros-finance/sdk for Solana/Saros interactions
Wraps SDK functions with error handling
Formats data for AI-friendly consumption

Development

Adding New Tools

Create tool handler in src/tools/:

export async function myNewTool(args, services) {
  const { param1, param2 } = args;

  // Tool logic here

  return {
    content: [{
      type: "text",
      text: "Result text"
    }]
  };
}

// In ListToolsRequestSchema handler
{
  name: "my_new_tool",
  description: "Tool description",
  inputSchema: { /* schema */ }
}

// In CallToolRequestSchema handler
case "my_new_tool":
  return await myNewTool(args, this.services);

Testing

# Test with example wallet
node examples/test-client.js

# Manual testing
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node src/index.js

Deployment

Local Deployment

npm start

Railway/Render

Create new service
Connect GitHub repo
Set build command: npm install
Set start command: npm start

Docker (Optional)

FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["npm", "start"]

Roadmap

Add DLMM-specific features (advanced orders, dynamic fees)
Implement real-time price feeds
Add transaction execution tools
Multi-wallet management
Historical performance tracking
Web dashboard UI

Contributing

Contributions welcome! Please:

Fork the repo
Create a feature branch
Commit changes
Submit a PR

License

MIT License - see LICENSE file

Hackathon Submission

Project: Saros MCP Server Category: SDK Usage & Developer Tools Hackathon: Saros $100K Hackathon

Key Innovations

First MCP server for Saros DeFi
AI-native portfolio management
Natural language DeFi interactions
Foundation for autonomous trading agents

Demo

Test Client: npm test
Telegram Bot: See examples/telegram-bot.js
Video Walkthrough: [Link TBD]

Resources

Support

GitHub Issues: Report bugs
Telegram: Community
Email: your-email@example.com

Built with ❤️ for the Saros Hackathon