npm package: 7bins-mcp
Description: OpenClaw plugin — 7bins Meteora LP position manager MCP bridge
Latest version: 1.0.7

# 7bins MCP Plugin — Installation and Usage Guide

Complete step-by-step guide for installing OpenClaw and the 7bins MCP plugin to manage Meteora DLMM liquidity positions.

---

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Installing OpenClaw](#installing-openclaw)
3. [Installing the 7bins MCP Plugin](#installing-the-7bins-mcp-plugin)
4. [Configuring the Plugin](#configuring-the-plugin)
5. [Authentication](#authentication)

---

## Prerequisites

Before you begin, ensure you have:

- **Node.js 22+** installed ([Download](https://nodejs.org/))
- **npm 10+** or **pnpm 9+**
- **LLM Provider Credentials** (OpenAI, Anthropic, or Google Gemini API key)
- **A Solana wallet** with a private key (for authentication)
- **Access to a 7bins MCP server** (your deployed server URL or `http://localhost:3100` for local development)

---

## Installing OpenClaw

### Step 1: Install OpenClaw globally

```bash
npm install -g openclaw@latest
```

### Step 2: Verify installation

```bash
openclaw --version
```

You should see the version number (e.g., `0.8.0` or higher).

### Step 3: Run onboarding

```bash
openclaw onboard --install-daemon
```

This will:
- Set up the OpenClaw configuration directory (`~/.openclaw/`)
- Create the initial `openclaw.json` configuration file
- Prompt you to configure your LLM provider (OpenAI, Anthropic, or Gemini)
- Install the OpenClaw daemon service

**Follow the prompts** to:
1. Select your LLM provider
2. Enter your API key
3. Choose your preferred model

---

## Installing the 7bins MCP Plugin

### Step 1: Install the plugin from npm

```bash
openclaw plugins install 7bins-mcp
```

This will:
- Download the plugin from npm
- Install it to `~/.openclaw/extensions/7bins-mcp/`
- Register it with OpenClaw

### Step 2: Verify installation

```bash
openclaw plugins list
```

You should see `7bins-mcp` in the list of installed plugins.

---

## Configuring the Plugin

### Step 1: Open your OpenClaw configuration

The configuration file is located at:
- **macOS/Linux**: `~/.openclaw/openclaw.json`
- **Windows**: `%USERPROFILE%\.openclaw\openclaw.json`

You can edit it with any text editor, or use:

```bash
openclaw config edit
```

### Step 2: Enable the plugin and tools

Add the following to your `openclaw.json`:

```json
{
  "plugins": {
    "allow": ["7bins-mcp"]
  },
  "tools": {
    "allow": ["7bins-mcp", "group:openclaw"]
  }
}
```

### Step 3: Configure your MCP server URL (optional)

If your MCP server is deployed on AWS or another remote server, configure the URL:

```json
{
  "plugins": {
    "allow": ["7bins-mcp"],
    "entries": {
      "7bins-mcp": {
        "config": {
          "serverUrl": "https://your-mcp-server.com"
        }
      }
    }
  },
  "tools": {
    "allow": ["7bins-mcp", "group:openclaw"]
  }
}
```

**Important notes:**
- The `serverUrl` should be the **base URL** of your MCP server (without `/mcp` suffix)
- The plugin automatically appends `/mcp` to the URL when making requests
- If you include `/mcp` in the URL, it will be automatically removed
- **Examples:**
  - ✅ `"serverUrl": "https://mcp.7bins.com"` → requests go to `https://mcp.7bins.com/mcp`
  - ✅ `"serverUrl": "https://mcp.7bins.com/mcp"` → automatically becomes `https://mcp.7bins.com/mcp`
  - ✅ `"serverUrl": "http://localhost:3100"` → requests go to `http://localhost:3100/mcp`
- If `serverUrl` is not specified, it defaults to `http://localhost:3100`

### Step 4: Save and restart OpenClaw

After making changes, restart OpenClaw:

```bash
openclaw restart
```

Or if running manually:

```bash
# Stop the daemon
openclaw stop

# Start it again
openclaw start
```

---

## Authentication

Before you can use the position management tools, you must authenticate with your Solana wallet. The plugin supports two authentication methods:

### Method 1: In-Chat Authentication (Recommended)

This method uses the `meteora_auth` tool directly in your OpenClaw chat session.

#### Step 1: Start OpenClaw

```bash
openclaw chat
```

#### Step 2: Authenticate with your private key

In the chat, ask OpenClaw to authenticate you. You can provide your private key in one of these formats:

**Base58 keypair string** (as exported by Solana CLI or Phantom):
```
Authenticate me for Meteora LP bot. My private key is: 5J3mBbA58q6W1... (your full base58 keypair)
```

**JSON byte array** (Solana CLI format):
```
Authenticate me for Meteora LP bot. My private key is: [12,34,56,...,128 numbers]
```

**Hex string** (128 characters):
```
Authenticate me for Meteora LP bot. My private key is: 010203... (128 hex characters)
```

#### Step 3: The plugin handles the rest

The `meteora_auth` tool will:
1. Parse your private key locally (it never leaves your machine)
2. Derive your wallet address
3. Fetch a challenge message from the server
4. Sign the challenge locally using your private key
5. Exchange the signature for a session token
6. Save the token to `~/.openclaw/extensions/7bins-mcp/.token`

**You're now authenticated!** The token is valid for 7 days.

### Method 2: CLI Authentication (Alternative)

If you have a Solana keypair JSON file (e.g., from `solana-keygen`), you can authenticate via the command line:

#### Step 1: Run the authentication CLI tool

```bash
npx 7bins-mcp-auth --keypair ~/.config/solana/id.json --url https://your-mcp-server.com
```

**Options:**
- `--keypair <path>`: Path to your Solana keypair JSON file (default: `~/.config/solana/id.json`)
- `--url <server-url>`: MCP server base URL (default: `http://localhost:3100`)
- `--no-save`: Don't save the token (it will still be printed to stdout)

#### Step 2: Token is saved automatically

The token is automatically saved to `~/.openclaw/extensions/7bins-mcp/.token`, and the plugin will use it on the next request.

**For Node.js < 19:**
```bash
npm install @noble/ed25519
npx 7bins-mcp-auth --keypair ~/.config/solana/id.json
```

### Token Refresh

Tokens expire after 7 days. To refresh:

1. **In-chat**: Simply call `meteora_auth` again with your private key
2. **CLI**: Run `npx 7bins-mcp-auth` again

The plugin automatically picks up the new token on the next request.

---

## Using the Plugin

### Starting OpenClaw Chat

```bash
openclaw chat
```

### Available Tools

Once authenticated, you can use these tools in your chat:

| Tool | Description |
|------|-------------|
| `meteora_auth` | Authenticate with your Solana wallet |
| `get_pool_data` | Get information about a Meteora DLMM pool |
| `list_opened_positions` | List all your active positions |
| `get_position_data` | Get detailed data for a specific position |
| `get_position_status` | Get the current status of a position |
| `get_position_configuration` | Get the full configuration of a position |
| `get_dashboard_stats` | Get portfolio dashboard statistics |
| `open_position` | Open a new DLMM liquidity position |
| `add_liquidity` | Add liquidity to an existing position |
| `withdraw_liquidity` | Withdraw liquidity from a position |
| `close_position` | Close a position |

### Example Conversations

**Check your positions:**
```
> List all my active positions
```

**Get pool information:**
```
> Get pool data for address 7t4on6jZvR4Satv6h2WRhWXhfMHmggszk4uVv29CfCaq
```

**Open a new position:**
```
> Open a new position on pool 7t4on6jZvR4Satv6h2WRhWXhfMHmggszk4uVv29CfCaq with 100 USDC of token X and 50 USDC of token Y, using SPOT strategy
```

**Check position details:**
```
> Get full details for position address ABC123...
```

**View dashboard:**
```
> Show me my portfolio dashboard stats
```

---

## Troubleshooting

### Plugin not found after installation

**Problem:** `openclaw plugins list` doesn't show `7bins-mcp`

**Solution:**
1. Verify npm installation: `npm list -g openclaw`
2. Check plugin installation: `ls ~/.openclaw/extensions/7bins-mcp/`
3. Reinstall: `openclaw plugins uninstall 7bins-mcp && openclaw plugins install 7bins-mcp`

### Authentication fails with 401 error

**Problem:** Tools return "Not authenticated" errors

**Solution:**
1. Check if token exists: `cat ~/.openclaw/extensions/7bins-mcp/.token`
2. Verify token is not expired (tokens last 7 days)
3. Re-authenticate using `meteora_auth` tool or `npx 7bins-mcp-auth`
4. Ensure your wallet is registered on the 7bins platform

### Server connection errors

**Problem:** "MCP server 500" or connection refused errors

**Solution:**
1. Verify your `serverUrl` in `openclaw.json` is correct
2. Test the server URL manually:
   ```bash
   curl https://your-mcp-server.com/mcp
   ```
3. Check if the server requires authentication (some endpoints may be public)
4. Verify network connectivity and firewall settings

### Tools not available in chat

**Problem:** OpenClaw doesn't recognize the tools

**Solution:**
1. Verify plugin is enabled in `openclaw.json`:
   ```json
   {
     "plugins": { "allow": ["7bins-mcp"] },
     "tools": { "allow": ["7bins-mcp", "group:openclaw"] }
   }
   ```
2. Restart OpenClaw: `openclaw restart`
3. Check plugin logs: `openclaw logs`

### Private key parsing errors

**Problem:** `meteora_auth` fails with "Invalid private key"

**Solution:**
1. Ensure your private key is in one of the supported formats:
   - Base58: 64-byte keypair string
   - JSON array: `[1,2,3,...,64]` (exactly 64 numbers)
   - Hex: 128 hexadecimal characters
2. Remove any extra whitespace or newlines
3. For JSON array format, ensure it's valid JSON

### Token not persisting

**Problem:** Token is not saved after authentication

**Solution:**
1. Check directory permissions: `ls -la ~/.openclaw/extensions/7bins-mcp/`
2. Ensure write permissions: `chmod -R u+w ~/.openclaw/extensions/`
3. Try saving manually:
   ```bash
   echo "your-token-here" > ~/.openclaw/extensions/7bins-mcp/.token
   ```

### Node.js version issues

**Problem:** `npx 7bins-mcp-auth` fails on older Node versions

**Solution:**
1. Upgrade to Node.js 19+ (recommended)
2. Or install the fallback dependency:
   ```bash
   npm install @noble/ed25519
   npx 7bins-mcp-auth --keypair ~/.config/solana/id.json
   ```

---

## Advanced Configuration

### Using a custom token

If you have a token from another source, you can set it directly in `openclaw.json`:

```json
{
  "plugins": {
    "allow": ["7bins-mcp"],
    "entries": {
      "7bins-mcp": {
        "config": {
          "serverUrl": "https://your-mcp-server.com",
          "sessionToken": "your-token-here"
        }
      }
    }
  }
}
```

**Token priority order:**
1. `plugins.entries.7bins-mcp.config.sessionToken` (from `openclaw.json`)
2. `~/.openclaw/extensions/7bins-mcp/.token` (from authentication tools)
3. No token (unauthenticated requests)