Bybit MCP Server

Bybit V5 trading for Claude Desktop, Claude Code, and Cursor. Linear and inverse perpetuals, spot, and options with Greeks, IV scanning, market regime detection, OI divergence scanning, and confirmation-based safety rails.

This MCP allows AI models to execute real trades with real money on Bybit. Models make mistakes. Markets move fast. You are the only safeguard between a bad model decision and your account. Use a testnet API key until you understand exactly what every tool does.

---

Why this one

There are several Bybit MCPs. Most are thin V5 REST wrappers with one tool per endpoint, no analytics, and no options support. This one is built for traders making actual decisions, not just querying the API.

	ajs-bybit-mcp (this repo)	Typical Bybit MCP
Options trading	Full stack: chains, Greeks, IV scanning, skew and term structure, payoff math, safe place/close	Not supported
Market analytics	Regime detection (risk_on / risk_off / choppy), OI divergence scan, crowded positioning scan, volume spike scan	Individual endpoint queries
Account view	Single get_account_status call: balance, margin in use, unrealised PnL, and all positions across perps, spot, and options	Multiple calls for wallet, positions, orders
Consolidated market data	get_market_data returns price, funding, OI, klines, and top-20 orderbook in one call	One endpoint per data type
Execution safety	CONFIRM required on every execution tool + dry_run preview on every order	None beyond testnet default
Options safety	Naked short blocked by default, partial-short detection, premium % of balance guard	N/A
Token efficiency	Compact responses by default: orderbook summary (5 fields) instead of 20-level arrays, rounded numerics, optional chain compact mode	Full arrays, raw floats
Test coverage	198 tests across 19 suites	Usually unstated
Scope	Trading decisions	Bybit V5 CRUD

If you want "what's the price of BTC" and a place-order endpoint, the other Bybit MCPs will do fine. If you want a toolkit for real trading workflow — regime views, positioning scans, options flow, safe execution — use this one.

---

Scope

Bybit V5 API for AI agents, with confirmation-based safety rails. Exposes Bybit's trading functionality cleanly to any MCP-compatible model (Claude Desktop, Claude Code, Cursor, or any client that speaks MCP over stdio).

This is not a trading bot, strategy framework, backtesting tool, or multi-exchange aggregator. If you want different behaviour, fork it.

---

Tools

Account & Market

Tool	Description
get_account_status	Balance, free capital, margin in use, unrealised PnL, and all open positions (perps, spot, options)
get_market_data	Price, funding rate, open interest, klines, and orderbook summary (or full depth with includeOrderbook=true) for a single linear perp
get_market_regime	BTC trend + aggregate funding sentiment across top-20 perps - returns risk_on / risk_off / choppy
scan_market	Scan all linear perps for OI divergence, crowded positioning, or volume spikes
get_ohlc	Raw OHLC candles for any symbol and category

Perpetuals & Spot Execution

Tool	Description
place_trade	Place a market or limit order on a linear perp, inverse perp, or spot market
close_position	Close an open position fully or partially
manage_position	Update SL, TP, or trailing stop on an open perp position

Options (requires ENABLE_OPTIONS=true)

Tool	Description
options_market	Consolidated options data: browse chains, get single-contract quotes with Greeks, scan for IV anomalies, and view regime signals (ATM IV, skew, term structure). Use the action parameter to select mode: chain, quote, scan, or regime.
get_option_payoff	Compute expiry payoff for one or more legs - max loss, max profit, breakevens. Pure math, no API call.
place_option_trade	Place a single-leg option order with dry-run support and safety guards
close_option_position	Close an open option position fully or partially

Option premium is charged in USDC. USDT is not used for options settlement. Ensure you have USDC balance before placing option trades.

---

Setup

1. Get Bybit API keys

Create an API key at Bybit API Management.

Required permissions: Read + Trade. Never enable: Withdrawal or Transfer. This MCP does not need them, and enabling them creates unnecessary risk. Recommended for first use: Read-only. This lets you explore all data tools (get_market_data, scan_market, get_ohlc, options_market, etc.) without execution risk. Add Trade permissions when you're ready.

For testnet keys, use Bybit Testnet.

2. Configure Claude Desktop

Add to your Claude Desktop config file:

Platform	Config path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bybit": {
      "command": "npx",
      "args": ["-y", "ajs-bybit-mcp"],
      "env": {
        "BYBIT_API_KEY": "your_api_key",
        "BYBIT_API_SECRET": "your_api_secret",
        "BYBIT_TESTNET": "true"
      }
    }
  }
}

Start with BYBIT_TESTNET=true. Remove it or set to false only after you are comfortable with how the tools behave.

Restart Claude Desktop after saving.

Install from source (contributors)

git clone https://github.com/Ajshawit/bybit-mcp.git
cd bybit-mcp
npm install
npm run build

Then use node /absolute/path/to/bybit-mcp/dist/index.js instead of npx ajs-bybit-mcp in the config above.

---

Environment Variables

Variable	Required	Default	Description
BYBIT_API_KEY	Yes	-	Bybit V5 API key
BYBIT_API_SECRET	Yes	-	Bybit V5 API secret
BYBIT_TESTNET	No	false	Use Bybit testnet API (testnet.bybit.com). Recommended for first-time setup.
ENABLE_OPTIONS	No	false	Enable the 4 options tools
OPTIONS_ALLOW_NAKED_SHORT	No	false	Allow selling options without an offsetting long position. Naked short options carry unlimited or very large maximum loss.
OPTIONS_MAX_PREMIUM_PCT_BALANCE	No	none	Block option buys where premium exceeds N% of USDC balance

---

Safety

All execution tools (place_trade, close_position, manage_position, place_option_trade, close_option_position) require explicit CONFIRM from the user before submitting an order. Each supports dry_run=true to preview the order without placing it.

Option short selling is blocked by default unless OPTIONS_ALLOW_NAKED_SHORT=true is set or an offsetting long position exists. The naked short guard also catches partial naked shorts (e.g. selling 2 contracts when only 1 long exists).

---

Example Conversation

You:   What's the market looking like?

Claude: [calls get_market_regime]
        Intraday regime is risk_off. BTC is below both SMAs at $75,190,
        trending bear. Funding sentiment is neutral.

You:   Any short setups?

Claude: [calls scan_market with filter=oi_divergence]
        AAVE showing OI divergence: price -20% in 24h but OI +21% in 4h
        with funding flipping negative. Fresh shorts entering.

You:   Short AAVE.

Claude: Here's the plan:
        - AAVE short, 0.89 contracts @ ~$90.67
        - Margin: $27, leverage: 3x
        - SL: $93, TP: $87
        - R:R: 1.57:1

        Reply CONFIRM to proceed.

You:   CONFIRM

Claude: [calls place_trade with dry_run=true]
        Dry run verified. Estimated fill $90.49, notional $81, margin $27.
        Warning: uses 25% of free balance. wouldSubmit: true.

        [calls place_trade with dry_run=false]
        Filled 0.89 AAVE @ $90.67. Order ID: b53a54b4-...

The model presents a plan, waits for CONFIRM, verifies via dry run, then submits. This flow applies to all execution tools.

---

Development

npm test            # run all tests
npm run test:watch  # watch mode
npm run dev         # auto-rebuild on file changes (TypeScript watch)
npm run build       # compile to dist/

Tests: 388 passing across 38 suites.

---

License

MIT

---

Disclaimer

This software is provided as-is under the MIT License. It is not financial advice. The authors are not responsible for any trades executed through this tool. You are solely responsible for your own trading decisions and any resulting financial outcomes. Use at your own risk.