btse-mcp

MCP server for the BTSE Futures API. Enables AI agents (Claude Desktop, Cursor, LangChain) to query market data, manage positions, and place orders on BTSE via natural language.

Prerequisites

• Python 3.11 or higher — check with python --version
• pip — check with pip --version
• A BTSE account (testnet or live)

Multiple Python versions (Anaconda etc): use the full path explicitly:

/usr/local/bin/python3.14 -m pip install -e .
/Library/Frameworks/Python.framework/Versions/3.14/bin/btse-mcp --help

Use that same full path in the Claude Desktop config (Step 4).

Step 1 — Get API keys from BTSE

Testnet (recommended first)

1. Register at https://testnet.btse.io
2. Go to Account → API tab → New API
3. Save the API Key and Passphrase — the passphrase is shown only once and is your api_secret
4. Set permissions: Read + Trading (add Transfer if needed)

Live

Same steps at https://btse.com

Step 2 — Install

# Clone the repo
git clone https://github.com/xbotlive/btse-mcp.git
cd btse-mcp

# Install — adds `btse-mcp` command to your PATH
pip install -e .

# Verify
btse-mcp --help

Virtualenv users: if btse-mcp is not found after install, use the full path:

• macOS/Linux: ~/.venv/bin/btse-mcp
• Windows: ~\.venv\Scripts\btse-mcp.exe

You will need this full path in the Claude Desktop config (Step 4).

Step 3 — Configure accounts

# Add a testnet account
btse-mcp config --account-id testnet
# Prompts:
#   API Key    → paste your API key
#   API Secret → paste your passphrase (input is hidden)
#   Use testnet? [y/N] → y

# Verify the connection — should print BTC-PERP last price
btse-mcp test testnet

# Add your live account when ready
btse-mcp config --account-id main
# Same prompts — answer 'n' to testnet

# See all configured accounts
btse-mcp list

Credentials are stored encrypted at ~/.config/btse-mcp/accounts.enc.

Unified Futures Wallet: If your BTSE account has been upgraded to the Unified Futures Wallet (all accounts from late 2024 onwards), account endpoints automatically use the v2.2 API. No action needed.

Step 4 — Connect to Claude Desktop

btse-mcp install-claude

This auto-writes the correct config for your OS and creates the file if it doesn't exist. Then restart Claude Desktop.

Manual alternative: if the command fails, add this to your config file directly:

OS	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": {
    "btse": {
      "command": "btse-mcp",
      "args": ["start"]
    }
  }
}

Virtualenv users: replace "btse-mcp" with the full path, e.g.:

"command": "/Users/yourname/.venv/bin/btse-mcp"

Open a new chat in Claude Desktop — you should see a tools icon (🔧) in the input bar.

Test it:

"What is the BTC-PERP mark price on BTSE using account testnet?"

Step 5 — Connect to Cursor

Open Cursor → Settings → MCP → Add Server and enter:

{
  "name": "btse",
  "command": "btse-mcp",
  "args": ["start"]
}

Then use natural language in Cursor chat:

"Show my open BTSE positions" "Place a limit buy on BTC-PERP at 60000 size 1 using account testnet"

Alternative: run without installing

# From the repo root, no pip install required
python -m btse_mcp start

Tool list

All tools accept an optional account_id parameter (defaults to "default"). Pass "account_id": "testnet" to route to your testnet account.

Multi-account usage

btse-mcp list           # list all configured accounts
btse-mcp test main      # test a specific account

In prompts, specify the account explicitly:

"Using account testnet, show my BTC-PERP position"

Symbol naming

Use new-style perpetual names: BTC-PERP, ETH-PERP, SOL-PERP, etc.

Auth

BTSE uses HMAC-SHA384. The signature is:

HMAC-SHA384(api_secret, url_path + nonce + request_body)

Sent via headers: request-api, request-nonce, request-sign. See docs/integration.md for full details and worked examples.

Running tests

pip install pytest
pytest -v

Auth signature tests run against the worked examples in the BTSE docs — no live API connection needed.

Troubleshooting

Disclaimer

Futures trading involves significant risk of loss. Always test on testnet before using live credentials. Never commit API keys to version control — they are stored encrypted locally and excluded via .gitignore.