MCP

Lucyd MCP Server

Connect Claude, Cursor or any MCP-compatible AI agent to Lucyd. Browse markets, read the order book, trade, close positions and collect winnings by asking in plain language.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants use external tools. The Lucyd MCP server is a small program that runs on your computer. Your agent asks it for markets, prices or trades; the server calls the Lucyd API and order book, signs orders with your wallet key locally and returns the result.

Available tools

Market data

No wallet needed

list_markets

Markets filtered by state and period

get_market

Rules, strike, end date and outcome token ids of a market

get_order_book

Bids, asks, best bid, best ask and mid of an outcome

list_trades

Recent trades by market or trader

get_positions

Tokens held, average price, value and profit

get_trader_stats

Profit, volume and win rate of a wallet

get_pnl_history

Profit over time

top_traders

Leaderboard

Trading

Signed with your wallet key

place_order

Limit or market order, buy or sell Up or Down

close_position

Sell everything you hold on a market right away

cancel_orders

Cancel by id, all on a market, or all

get_open_orders

Your resting orders

Wallet

On-chain, needs a little Sepolia ETH for gas

get_wallet

Address, ETH and USDC balances, approvals

approve_trading

One-time approvals for the Exchange contract

set_auto_redeem

Turn automatic payout of winnings on or off

redeem

Collect the payout of a resolved market

Quickstart

1. Install Node.js

You need Node.js 18 or newer. Your agent runs the server with npx -y @lucyd/mcp, which downloads the build for your system on first run and verifies its checksum. Nothing else to install.

2. Prepare a wallet

Use a separate wallet for your agent and copy its private key. Skip the key to use the server read-only.

The key gives full control of the wallet. It stays on your computer: the server signs locally and never sends it anywhere. Keep only what you are ready to trade in this wallet.

3. Add to Claude Code

bash

claude mcp add lucyd -e LUCYD_PRIVATE_KEY=0xYOUR_KEY -- npx -y @lucyd/mcp

Or add to Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and restart Claude:

claude_desktop_config.json

{
  "mcpServers": {
    "lucyd": {
      "command": "npx",
      "args": ["-y", "@lucyd/mcp"],
      "env": {
        "LUCYD_PRIVATE_KEY": "0xYOUR_KEY"
      }
    }
  }
}

Or add to Cursor

Add the same block to ~/.cursor/mcp.json:

~/.cursor/mcp.json

{
  "mcpServers": {
    "lucyd": {
      "command": "npx",
      "args": ["-y", "@lucyd/mcp"],
      "env": {
        "LUCYD_PRIVATE_KEY": "0xYOUR_KEY"
      }
    }
  }
}

On Windows, if the client cannot start npx, use "command": "cmd" with "args": ["/c", "npx", "-y", "@lucyd/mcp"]. Prefer not to use Node.js? Download the binary from Releases and use its path as the command.

Before the first trade

The wallet needs USDC to buy and a little Sepolia ETH for the one-time approvals and for redemptions. Ask your agent to check your wallet and approve trading: it calls get_wallet and approve_trading. Trading itself costs no gas, the exchange settles fills on chain.

Lucyd currently runs on the Ethereum Sepolia testnet with test USDC.

Example prompts

Once connected, your agent understands requests like:

›

"Show the open 1h markets and the order book of the current one"

›

"What is the probability that BTC goes Up in the current 15m market?"

›

"Buy 10 Up tokens in the current 15m market at 0.55 or better"

›

"Close my position in the 5m market"

›

"What are my positions and total profit this week?"

›

"Cancel all my orders"

›

"Turn on automatic payout of my winnings"

Settings

Set as environment variables in the server config, next to the key.

LUCYD_PRIVATE_KEY

Wallet key that signs orders and transactions. Without it the server is read-only

LUCYD_MAX_ORDER_USD

Largest buy order in USDC

default: 100

LUCYD_READ_ONLY

Set to true to turn off every tool that trades or sends transactions

default: false

LUCYD_RPC_URL

Sepolia RPC node

default: https://ethereum-sepolia-rpc.publicnode.com

LUCYD_API_URL

Markets API

default: https://api.testnet.lucyd.trade

LUCYD_CLOB_URL

Order book

default: https://clob.testnet.lucyd.trade

Safety

The key never leaves your computer. Only signed orders and transactions are sent.
The server tells your agent to ask you before trading, but the final call is the agent's. Keep LUCYD_MAX_ORDER_USD low.
Want data only? Leave out the key or set LUCYD_READ_ONLY=true.

Source code

The server is open source under the MIT license: github.com/lucyd-trade/mcp-server. Read the code, build it yourself with cargo install --git https://github.com/lucyd-trade/mcp-server, or open an issue or pull request.