o2 MCP Server

Trade on o2 Exchange using natural language. The o2 MCP Server connects AI assistants like Claude and Codex to o2's on-chain order book, letting you place orders, check balances, and analyze markets just by asking.

No SDK code to write. No price scaling to worry about. Just tell the AI what you want to do.

Quick Start

1. Clone and Build

git clone https://github.com/o2-exchange/o2-mcp-server.git
cd o2-mcp-server
bun install
bun run build

2. Add Your Private Key

Create a .env file in the project root:

cp .env.example .env

Open .env and add your credentials:

O2_NETWORK=mainnet
O2_PRIVATE_KEY=your_private_key

The server loads this file automatically on startup. Your private key stays local and never ends up in client configs or shell history.

Variable	Description	Values
O2_NETWORK	Network to connect to	devnet, testnet, or mainnet
O2_PRIVATE_KEY	Owner private key for trading	Your wallet private key

3. Connect to Your AI Client

Claude Code

From inside the o2-mcp-server directory, run:

claude mcp add o2-mcp-server -- node "$(pwd)/dist/stdio.js"

This resolves the absolute path for you, so there's nothing to manually edit.

Open a new Claude Code session, then run /mcp to confirm the server is connected.

Codex

From inside the o2-mcp-server directory, grab the absolute path:

echo "$(pwd)/dist/stdio.js"

Then add to .codex/config.toml, replacing the path with the output from above:

[mcp_servers.o2_mcp]
command = "node"
args = ["/your/absolute/path/to/dist/stdio.js"]

How to Use It

Once the server is connected, interact with o2 through plain English. No special syntax needed.

Create an Account and Session

Before trading, you need a trading account and an active session:

Initialize trading account and create a session to trade ETH/USDC

The AI will:

1. Create a trading account, deriving the owner address from O2_PRIVATE_KEY
2. Create a 48-hour session for the ETH/USDC market
3. Return your Account ID and Session ID for subsequent trades

Place Trades

Once your session is active, place orders in plain language:

Market buy 2 USDC worth of ETH

The AI looks up the current market price, calculates the correct quantity, and submits the order on-chain. You get back a transaction ID and order confirmation.

More examples:

Place a limit buy for 100 FUEL at 0.025 USDC

Sell 50 USDC worth of ETH at market price

Cancel my open orders on ETH/USDC

Check Your Portfolio

What's my balance?

Show my open orders on FUEL/USDC

What orders have I filled today?

Analyze Markets

Ask for a market overview in plain English:

Give me a technical analysis of ETH/USDC over the last 24 hours

The AI fetches RSI, MACD, Bollinger Bands, and other indicators, then summarizes the trend, momentum, and volatility into a readable report.

You can also use the built-in prompt for a structured analysis:

/o2-mcp:Analyze_Market <market_id> <period>

Example:

/o2-mcp:Analyze_Market 0x09c17f779eb0a7658424e48935b2bef24013766f8b3da757becb2264406f9e96 24h

Example Conversation

Here is a real session showing the full flow from account creation through trading and market analysis.

View full example conversation

1. Setting up: "Initialize trading account and create a session to trade ETH/USDC"

The AI creates the account, generates a session, and reports back:

• Trading Account ID: 0x6bc9...bb64
• Session ID: c149b2a6-...
• Session expires in ~48 hours

2. Trading: "Market buy 2 USDC worth of ETH"

The AI checks the current ETH price (~$3,323), places the order, and confirms:

• Order type: Market Buy
• Amount: 2 USDC worth (~0.0006 ETH)
• Transaction submitted on-chain

3. Analysis: "Create a minimal financial analysis of the ETH/USDC market"

The AI pulls indicators and returns a summary:

• Price: $3,329.79 (-0.36% / 24h)
• RSI: 54.05 (neutral)
• MACD: Bearish crossover, but improving
• Bollinger Bands: Consolidating near the middle
• Verdict: Neutral momentum, watch for breakout above $3,390 or below $3,290

Sample Prompts

Copy and paste these to get started:

Goal	What to Say
Get started	"Initialize trading account and create a session to trade ETH/USDC"
Market buy	"Market buy 5 USDC worth of FUEL"
Limit order	"Place a limit buy for 200 FUEL at 0.024 USDC"
Cancel orders	"Cancel all my open orders on FUEL/USDC"
Check balance	"What's my current balance?"
Market analysis	"Give me a technical analysis of ETH/USDC for the last 24h"
Quick price check	"What's the current price of FUEL/USDC?"
Order book	"Show me the order book depth for ETH/USDC"

Available Tools

These tools run behind the scenes. You don't need to call them directly.

Market Data

Tool	Description
o2_markets_list	List all available trading markets
o2_market_ticker	Real-time ticker data including price, volume, and 24h change
o2_depth	Order book depth with bids and asks
o2_trades	Recent trade history
o2_indicators	16+ technical indicators including RSI, MACD, Bollinger Bands, VWAP, and more

Trading and Account Management

Tool	Description
o2_account_create	Create a new trading account
o2_session_create	Create a trading session, valid for 48 hours
o2_sessions_list	List all stored sessions
o2_session_get	Get details of a specific session
o2_place_order	Place orders: Market, Limit, FillOrKill, or PostOnly
o2_cancel_order	Cancel an existing order
o2_orders	View order history
o2_balance	Check asset balances

Order Types

Type	Description
Limit	Standard limit order at a specific price. This is the default
Market	Execute immediately at the best available price
FillOrKill	Fill the entire order or cancel it. No partial fills
PostOnly	Maker-only order that adds liquidity. Rejected if it would match immediately

Technical Indicators

The o2_indicators tool supports 16+ indicators in two output modes:

Snapshot Mode (default): Returns the latest value along with metadata, previous values, deltas, and derived fields like %B, bandwidth, and ATR distances.

Window Mode: Returns arrays of historical values aligned to timestamps. Useful for charting and time-series analysis.

Category	Indicators
Moving Averages	sma_20, sma_50, ema_12, ema_26, vwap
Momentum	rsi_14, mfi_14, cci_20, stoch
Trend	adx_14, plus_di, minus_di, macd
Volatility	bbands, atr_14
Volume	obv

Session Management

Sessions are persisted to ~/.o2-mcp/sessions.json and reused across calls. They expire after 48 hours by default.

The AI manages sessions automatically, creating new ones when needed and reusing active ones. You can also ask directly:

List my active sessions

Show details for session c149b2a6-...

Troubleshooting

/mcp shows "No running MCP servers"

• Open a new Claude Code session after adding the server. Existing sessions do not pick up config changes.
• Check that dist/stdio.js exists in the project directory. If it does not, run bun run build.
• Make sure the path in your config is absolute (for example, /Users/you/o2-mcp-server/dist/stdio.js). Relative paths like ./dist/stdio.js will not work.

Tools are connecting to the wrong network

Check your .env file in the project root and verify the O2_NETWORK value is set to the network you want (devnet, testnet, or mainnet).

Session expired

Sessions last 48 hours. If you see a session error, ask:

Create a new session for ETH/USDC

The AI will create a fresh session and continue trading.