whitebit-mcp 1.0.0__tar.gz

whitebit_mcp-1.0.0/.dockerignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+tests/
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.vscode/
+.idea/
+.git/
+README.md
+RULES.md
+LESSONS.md
+AGENTS.md
+CLAUDE.md
+AI/
+.env
+docker-compose*.yml
+Dockerfile*
+*.md
+.gitignore
+.github/
+.claude/
+.end

whitebit_mcp-1.0.0/.env.example

@@ -0,0 +1,10 @@
+# WhiteBIT MCP Server — environment configuration
+# Copy this file to .env and set values as needed.
+#
+# This is the only server-side setting. API keys are NOT configured here —
+# they are passed directly as parameters in each tool call so the AI client
+# can supply them from conversation context.
+
+# WhiteBIT API base URL.
+# Override for testnet or custom deployments.
+WHITEBIT_BASE_URL=https://whitebit.com

whitebit_mcp-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Something isn't working as expected
+labels: bug
+---
+
+## Describe the bug
+
+A clear description of what the problem is.
+
+## Steps to reproduce
+
+1. Start the server with `...`
+2. Send tool call `...`
+3. Observe `...`
+
+## Expected behaviour
+
+What you expected to happen.
+
+## Actual behaviour
+
+What actually happened. Include any error messages or stack traces.
+
+## Environment
+
+- whitebit-mcp version / git commit:
+- `whitebit-python-sdk` version (`pip show whitebit-python-sdk`):
+- Python version:
+- How you're running the server (Docker / local):
+- AI client (Cursor / Claude Code / Claude Desktop):

whitebit_mcp-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Suggest a new tool or improvement
+labels: enhancement
+---
+
+## What would you like?
+
+A clear description of the feature or tool you'd like added.
+
+## Which SDK client / WhiteBIT API endpoint does this map to?
+
+Link to the relevant WhiteBIT API docs if applicable:
+https://docs.whitebit.com/
+
+## Why is this useful?
+
+Describe the use case this would enable.
+
+## Anything else?
+
+Additional context, examples, or references.

whitebit_mcp-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Summary
+
+<!-- What does this PR do? -->
+
+## Changes
+
+<!-- List the files changed and why -->
+
+## Checklist
+
+- [ ] `ruff check .` passes
+- [ ] `ruff format --check .` passes
+- [ ] `mypy --strict server.py` passes with zero errors
+- [ ] If a new SDK client was added: `llms.txt` and `README.md` tool count updated
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`

whitebit_mcp-1.0.0/.github/workflows/mirror.yml

@@ -0,0 +1,84 @@
+name: Mirror to Public Repo
+
+on:
+  push:
+    branches: [main, new-mcp, mcp-publishing]
+
+env:
+  TARGET_REPO: whitebit-exchange/whitebit-mcp
+  ROBOT_NAME: WhiteBit Bot
+  ROBOT_EMAIL: bot@whitebit.com
+
+jobs:
+  publish:
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/mcp-publishing'
+    uses: ./.github/workflows/publish-mcp.yml
+    secrets: inherit
+
+  mirror:
+    needs: publish
+    if: always() && (needs.publish.result == 'success' || needs.publish.result == 'skipped')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Tailscale
+        uses: tailscale/github-action@v3
+        with:
+          oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
+          oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
+          tags: tag:ci
+          use-cache: 'true'
+
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: Checkout target repo
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ env.TARGET_REPO }}
+          token: ${{ secrets.ROBOT_GITHUB_TOKEN }}
+          path: target-repo
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Sync files
+        run: |
+          # Clear target (keep .git/)
+          find target-repo -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +
+
+          # Copy files, excluding sensitive and internal ones
+          rsync -av \
+            --exclude='.git/' \
+            --exclude='.github/' \
+            --exclude='.env' \
+            --exclude='.mcp.json' \
+            --exclude='.claude/' \
+            --exclude='.idea/' \
+            --exclude='.venv/' \
+            --exclude='__pycache__/' \
+            --exclude='*.pyc' \
+            --exclude='.mypy_cache/' \
+            --exclude='.ruff_cache/' \
+            --exclude='.pytest_cache/' \
+            --exclude='.DS_Store' \
+            . target-repo/
+
+      - name: Commit and push
+        env:
+          ROBOT_GITHUB_TOKEN: ${{ secrets.ROBOT_GITHUB_TOKEN }}
+        run: |
+          cd target-repo
+
+          git config user.name "${{ env.ROBOT_NAME }}"
+          git config user.email "${{ env.ROBOT_EMAIL }}"
+          git add .
+
+          if ! git diff --quiet --staged; then
+            git commit \
+              -m "Sync from internal repo" \
+              -m "Source: ${{ github.repository }}@${{ github.sha }}"
+          else
+            echo "No changes to sync"
+          fi
+
+          git remote set-url origin https://x-access-token:${ROBOT_GITHUB_TOKEN}@github.com/${{ env.TARGET_REPO }}.git
+          git push origin HEAD:main

whitebit_mcp-1.0.0/.github/workflows/publish-mcp.yml

@@ -0,0 +1,54 @@
+name: Publish MCP to PyPI
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Tailscale
+        uses: tailscale/github-action@v3
+        with:
+          oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
+          oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
+          tags: tag:ci
+          use-cache: 'true'
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Bump version and publish to PyPI
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          CURRENT_VERSION=$(curl -s https://pypi.org/pypi/whitebit-mcp/json | python3 -c "import sys,json; print(json.load(sys.stdin)['info']['version'])" 2>/dev/null || echo "")
+          if [ -n "$CURRENT_VERSION" ]; then
+            MAJOR=$(echo "$CURRENT_VERSION" | cut -d. -f1)
+            MINOR=$(echo "$CURRENT_VERSION" | cut -d. -f2)
+            PATCH=$(echo "$CURRENT_VERSION" | cut -d. -f3)
+            NEW_VERSION="$MAJOR.$MINOR.$((PATCH + 1))"
+          else
+            NEW_VERSION="1.0.0"
+          fi
+          echo "New version: $NEW_VERSION"
+
+          sed -i "s/^version = \".*\"/version = \"$NEW_VERSION\"/" pyproject.toml
+
+          python -m pip install --upgrade build twine
+          python -m build
+          twine check dist/*
+          TWINE_USERNAME=__token__ TWINE_PASSWORD="${PYPI_TOKEN}" twine upload --repository pypi dist/* --verbose
+
+      - name: Test installation from PyPI
+        run: |
+          sleep 30
+          pip install whitebit-mcp
+          pip show whitebit-mcp | grep "Name: whitebit-mcp"
+          echo "Package published and installed successfully"

whitebit_mcp-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+.env
+.mcp.json
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+*.egg-info/
+dist/
+build/
+
+# IDE
+.idea/
+.vscode/
+
+# OS
+.DS_Store

whitebit_mcp-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to WhiteBit MCP Server
+
+Thank you for your interest in improving WhiteBit MCP Server.
+
+This server's tools are **auto-generated** from the official [WhiteBit Python SDK](https://github.com/whitebit-exchange/whitebit-python). This means the tool list, parameter names, and descriptions are derived programmatically — changes to individual tools should be addressed upstream in the SDK rather than in this repository.
+
+---
+
+## How to Contribute
+
+### Report a Bug
+
+If a tool returns an unexpected result, crashes, or behaves incorrectly:
+
+1. Open an [issue](../../issues/new?template=bug_report.md)
+2. Include:
+   - The **tool name** (e.g. `spot_trading__create_limit_order`)
+   - A **description of the expected vs. actual behavior**
+   - The **error message or response** you received (redact credentials)
+   - Your **environment**: OS, Docker version or Python version
+   - Steps to reproduce
+
+### Request a Feature or Tool
+
+If you'd like a new tool, endpoint, or behavior:
+
+1. Open an [issue](../../issues/new?template=feature_request.md)
+2. Describe:
+   - What you want the tool or feature to do
+   - Which WhiteBit API endpoint it corresponds to (link to [WhiteBit API docs](https://docs.whitebit.com) if applicable)
+   - Your use case
+
+> If the missing tool corresponds to a WhiteBit API endpoint that is already present in the Python SDK, it is likely that the tool just needs to be exposed — this can be done quickly.
+
+### Report a Documentation Issue
+
+If something in the README or docs is wrong, outdated, or unclear:
+
+1. Open an [issue](../../issues/new?template=docs.md) describing what needs to be corrected
+2. Include the section and a suggested correction if possible
+
+### Ask a Question
+
+For usage questions or integration help, open an [issue](../../issues/new) with the `question` label rather than sending email or a direct message. This keeps answers visible to others with the same question.
+
+---
+
+## What We Do Not Accept
+
+Because tool definitions are auto-generated from the SDK, we do **not** accept pull requests that:
+
+- Manually add, remove, or rename individual tools
+- Hardcode tool parameters that should come from the SDK
+- Modify generated tool signatures or descriptions
+
+If you believe a tool's signature or description is wrong, please report it as a bug — it is likely an issue in the upstream SDK.
+
+---
+
+
+## Issue Labels
+
+| Label | Meaning |
+|-------|---------|
+| `bug` | Something is broken |
+| `feature-request` | New tool or capability |
+| `docs` | Documentation fix or improvement |
+| `question` | Usage or integration question |
+| `upstream` | Root cause is in the WhiteBit SDK |
+| `wontfix` | Out of scope for this repository |

whitebit_mcp-1.0.0/Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.13-slim AS builder
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/
+
+WORKDIR /app
+
+COPY pyproject.toml .
+RUN uv sync --no-install-project --no-dev
+
+FROM python:3.13-slim
+
+COPY --from=builder /app/.venv /app/.venv
+ENV PATH="/app/.venv/bin:$PATH"
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+COPY server.py .
+
+EXPOSE 8000
+
+ENTRYPOINT ["python", "server.py"]

whitebit_mcp-1.0.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

whitebit_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: whitebit-mcp
+Version: 1.0.0
+Summary: MCP server that exposes the WhiteBIT exchange API as AI tools
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: whitebit-python-sdk>=1.1.6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'

whitebit_mcp-1.0.0/README.md

@@ -0,0 +1,302 @@
+<h1 align="center">WhiteBit MCP Server</h1>
+
+<p align="center">
+  <strong>Connect AI assistants to WhiteBit — trade, query, and manage your crypto portfolio through natural language.</strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python" alt="Python 3.11+" />
+  <img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=flat-square" alt="MCP compatible" />
+  <img src="https://img.shields.io/badge/transport-HTTP-0070f3?style=flat-square" alt="HTTP transport" />
+  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT license" />
+</p>
+
+---
+
+**WhiteBit MCP Server** is a [Model Context Protocol](https://modelcontextprotocol.io) server for the [WhiteBit](https://whitebit.com) cryptocurrency exchange. It exposes 100+ trading and account tools — auto-generated from the official WhiteBit Python SDK — that any MCP-compatible AI assistant can call through natural language. Check prices, manage orders, query balances, handle withdrawals, and more.
+
+Works with **Claude Code**, **Claude Desktop**, **Cursor**, and any other MCP-compatible client.
+
+> **Credentials are passed as tool parameters** (`api_key`, `secret_key`), not as server-level configuration. This means you can use different WhiteBit accounts within the same session without restarting the server.
+
+---
+
+## Prerequisites
+
+Before you start, make sure you have the following:
+
+| Requirement | Details |
+|-------------|---------|
+| **Docker & Docker Compose** | To run the server — [install Docker](https://docs.docker.com/get-docker/) |
+| **WhiteBit account** | Sign up at [whitebit.com](https://whitebit.com) |
+| **WhiteBit API key** | Profile → API keys → Create key (Read and/or Trade permissions) |
+| **MCP-compatible AI client** | Claude Code, Claude Desktop, Cursor, or any other MCP client |
+| **Python 3.11+** | Only if running without Docker |
+
+---
+
+## Quick Start
+
+### 1. Get your WhiteBit API credentials
+
+1. Log in to [whitebit.com](https://whitebit.com) → **Profile → API keys**
+2. Create a new key — choose **Read** and/or **Trade** permissions as needed
+3. Copy your **API Key** and **Secret Key**
+
+> Public endpoints (market data, tickers, order book) work without credentials. Private endpoints (account, trading) require both.
+
+### 2. Start the server
+
+```bash
+git clone https://github.com/your-org/whitebit-mcp.git
+cd whitebit-mcp
+docker compose up -d
+```
+
+The server starts at `http://localhost:8000`.
+
+### 3. Add to your AI client
+
+#### Claude Code (project-level)
+
+Create or update `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "whitebit-mcp": {
+      "type": "http",
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+Or via CLI:
+
+```bash
+claude mcp add whitebit-mcp "http://localhost:8000/mcp" -t http -s user
+```
+
+> Credentials (`api_key`, `secret_key`) are passed directly to each tool call — the server does not store them.
+
+That's it. Your AI can now trade on WhiteBit.
+
+---
+
+## Integrations
+
+### VS Code (Claude Extension)
+
+Install the [Claude extension for VS Code](https://marketplace.visualstudio.com/items?itemName=Anthropic.claude-code), then add the server via CLI:
+
+```bash
+claude mcp add whitebit-mcp "http://localhost:8000/mcp" -t http -s user
+```
+
+Or create `.mcp.json` in your project root to share the config with your team:
+
+```json
+{
+  "mcpServers": {
+    "whitebit-mcp": {
+      "type": "http",
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+Once added, use `/mcp` in the Claude chat panel to enable, disable, or reconnect the server.
+
+> `.mcp.json` is in `.gitignore` by default — if you want to share it with your team, remove it from `.gitignore` first.
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "whitebit-mcp": {
+      "type": "http",
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP settings (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "whitebit-mcp": {
+      "type": "http",
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+### Codex
+
+Add to your Codex MCP settings (`~/.codex/config.toml`):
+
+```toml
+[[mcp_servers]]
+name = "whitebit-mcp"
+type = "http"
+url  = "http://localhost:8000/mcp"
+```
+
+Or using the JSON format (`~/.codex/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "whitebit-mcp": {
+      "type": "http",
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+### OpenClaw
+
+Add via CLI:
+
+```bash
+openclaw mcp set whitebit-mcp '{"url":"http://localhost:8000/mcp"}'
+```
+
+Or add to your OpenClaw config under `mcp.servers`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "whitebit-mcp": {
+        "url": "http://localhost:8000/mcp"
+      }
+    }
+  }
+}
+```
+
+### Any MCP-compatible client
+
+The server uses standard **Streamable HTTP transport** on `http://localhost:8000/mcp`. No server-level authentication is required — credentials are supplied per tool call.
+
+---
+
+## Usage Examples
+
+Once connected, talk to your AI naturally. It will prompt you for credentials when needed:
+
+```
+"What's the current BTC/USDT price?"
+"Show me my spot account balance"
+"Place a limit buy order for 0.01 BTC at $95,000"
+"Cancel all my open orders on ETH/USDT"
+"What are the trading fees for BTC/USDT?"
+"Transfer 100 USDT from my main account to my trade account"
+"Show my open collateral positions"
+"Withdraw 500 USDT to address 0x..."
+```
+
+---
+
+## How Credentials Work
+
+Unlike header-based servers, this server receives `api_key` and `secret_key` as explicit parameters on every tool call. The AI assistant supplies them from the conversation context.
+
+| Endpoint type | Required parameters |
+|---------------|---------------------|
+| Public (market data) | `api_key`, `secret_key` |
+| Private (trading, account) | `api_key`, `secret_key` |
+| Account endpoints (OAuth2) | `api_key`, `bearer_token` |
+
+To obtain a `bearer_token` for account endpoints, use the `authentication__get_access_token` tool first.
+
+Use `get_credentials_status` to verify that credentials are being passed correctly.
+
+---
+
+## Configuration
+
+Copy `.env.example` to `.env` and adjust as needed:
+
+```env
+# WhiteBit API base URL
+WHITEBIT_BASE_URL=https://whitebit.com
+
+# Server port (default: 8000)
+PORT=8000
+
+# Log level: debug | info | warn | error
+LOG_LEVEL=info
+```
+
+
+## Available Tools
+
+100+ tools auto-generated from the official WhiteBit Python SDK across 19 categories:
+
+| Category | Tool prefix |
+|----------|-------------|
+| **Authentication** | `authentication__` |
+| **Account endpoints** | `account_endpoints__` |
+| **Public API v4** | `public_api_v4__` |
+| **Main account** | `main_account__` |
+| **Deposit** | `deposit__` |
+| **Withdraw** | `withdraw__` |
+| **Transfer** | `transfer__` |
+| **Codes** | `codes__` |
+| **Spot trading** | `spot_trading__` |
+| **Collateral trading** | `collateral_trading__` |
+| **Market fee** | `market_fee__` |
+| **Fees** | `fees__` |
+| **Convert** | `convert_estimate`, `convert_confirm`, `convert_history` |
+| **Crypto lending (flex)** | `crypto_lending_flex__` |
+| **Crypto lending (fixed)** | `crypto_lending_fixed__` |
+| **Sub-account** | `sub_account__` |
+| **Sub-account API keys** | `sub_account_api_keys__` |
+| **Mining pool** | `mining_pool__` |
+| **Credit line** | `credit_line__` |
+| **Credentials** | `get_credentials_status` |
+
+Tools are named `{category}__{method}` (e.g. `spot_trading__create_limit_order`). All tool names and parameters are derived directly from the SDK — no manual mapping.
+
+---
+
+## Security
+
+- Credentials are passed per tool call — **never stored** in server memory or logs
+- Use **read-only API keys** if you only need market data or account queries
+- For trading, create a dedicated API key with only the permissions you need
+- Consider IP whitelisting on your WhiteBit API key for additional protection
+
+---
+
+## Running without Docker
+
+Requirements: **Python 3.11+**
+
+```bash
+pip install -r requirements.txt
+
+# Run
+python server.py
+```
+
+The server listens on `PORT` (default `8000`).
+
+---
+
+## License
+
+[MIT](LICENSE)

whitebit_mcp-1.0.0/SECURITY.md

@@ -0,0 +1,41 @@
+# Security
+
+## Reporting a Vulnerability
+
+Please do **not** open a public GitHub issue for security vulnerabilities.
+
+Report them privately via [GitHub Security Advisories](https://github.com/whitebit-exchange/whitebit-mcp/security/advisories/new).
+Include a description of the issue, steps to reproduce, and potential impact.
+We will respond within 5 business days.
+
+---
+
+## Credential Model
+
+API keys are passed as parameters in each individual tool call. The server:
+
+- Uses them only to sign the outgoing WhiteBIT API request for that call
+- Does not store, log, cache, or persist them in any form
+- Does not write them to disk or transmit them to any party other than the WhiteBIT API
+
+Keys exist in memory only for the duration of a single HTTP request.
+
+---
+
+## Recommendations
+
+**Use minimal-permission API keys.** WhiteBIT lets you restrict each key to specific
+operations. Examples:
+
+| Use case | Permissions needed |
+|---|---|
+| Market data only | Any non-empty string (public endpoints do not validate keys) |
+| Balance and order queries | Read balance, Read orders |
+| Spot order placement | Read balance, Spot trading |
+| Full access | All permissions |
+
+**Keep keys out of your repository.** Do not commit API keys to `.env`, `docker-compose.yml`,
+or any configuration file. Pass them in conversation when using an AI client.
+
+**Use sub-accounts for automated strategies.** Create a dedicated sub-account with scoped API
+keys rather than using your main account keys.

whitebit_mcp-1.0.0/docker-compose.yml

@@ -0,0 +1,9 @@
+services:
+  whitebit-mcp:
+    build: .
+    image: whitebit-mcp
+    ports:
+      - "8080:8000"
+    environment:
+      WHITEBIT_BASE_URL: ${WHITEBIT_BASE_URL:-https://whitebit.com}
+    restart: unless-stopped

whitebit_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "whitebit-mcp"
+version = "1.0.0"
+description = "MCP server that exposes the WhiteBIT exchange API as AI tools"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = [
+    "whitebit-python-sdk>=1.1.6",
+    "mcp[cli]>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.4.0",
+    "mypy>=1.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+# server.py is a standalone script, not a library package.
+# This entry enables `pip install -e ".[dev]"` for local dev tooling only.
+include = ["server.py"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "A", "C4", "RUF"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

whitebit_mcp-1.0.0/requirements.txt

@@ -0,0 +1,2 @@
+whitebit-python-sdk>=1.1.6
+mcp[cli]>=1.0.0

whitebit_mcp-1.0.0/server.py

@@ -0,0 +1,352 @@
+import base64
+import hashlib
+import hmac as _hmac
+import inspect
+import json
+import os
+import time
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+from whitebit.core.client_wrapper import AsyncClientWrapper
+from whitebit.environment import WhitebitApiEnvironment
+from whitebit.authentication.client import AsyncAuthenticationClient
+from whitebit.account_endpoints.client import AsyncAccountEndpointsClient
+from whitebit.public_api_v4.client import AsyncPublicApiV4Client
+from whitebit.main_account.client import AsyncMainAccountClient
+from whitebit.deposit.client import AsyncDepositClient
+from whitebit.jwt.client import AsyncJwtClient
+from whitebit.withdraw.client import AsyncWithdrawClient
+from whitebit.transfer.client import AsyncTransferClient
+from whitebit.codes.client import AsyncCodesClient
+from whitebit.crypto_lending_fixed.client import AsyncCryptoLendingFixedClient
+from whitebit.crypto_lending_flex.client import AsyncCryptoLendingFlexClient
+from whitebit.fees.client import AsyncFeesClient
+from whitebit.sub_account.client import AsyncSubAccountClient
+from whitebit.sub_account_api_keys.client import AsyncSubAccountApiKeysClient
+from whitebit.mining_pool.client import AsyncMiningPoolClient
+from whitebit.credit_line.client import AsyncCreditLineClient
+from whitebit.collateral_trading.client import AsyncCollateralTradingClient
+from whitebit.market_fee.client import AsyncMarketFeeClient
+from whitebit.spot_trading.client import AsyncSpotTradingClient
+from whitebit.client import AsyncWhitebitApi, OMIT
+
+# ---------------------------------------------------------------------------
+# Credentials are passed as tool parameters (api_key, secret_key) so that
+# the LLM can supply them from conversation context.
+# WHITEBIT_BASE_URL remains an env-var-only config (useful for tests).
+# account_endpoints use OAuth2 Bearer auth; supply bearer_token to use them.
+# ---------------------------------------------------------------------------
+
+SUBCLIENT_CLASSES: dict[str, type] = {
+    "authentication": AsyncAuthenticationClient,
+    "account_endpoints": AsyncAccountEndpointsClient,
+    "public_api_v4": AsyncPublicApiV4Client,
+    "main_account": AsyncMainAccountClient,
+    "deposit": AsyncDepositClient,
+    "jwt": AsyncJwtClient,
+    "withdraw": AsyncWithdrawClient,
+    "transfer": AsyncTransferClient,
+    "codes": AsyncCodesClient,
+    "crypto_lending_fixed": AsyncCryptoLendingFixedClient,
+    "crypto_lending_flex": AsyncCryptoLendingFlexClient,
+    "fees": AsyncFeesClient,
+    "sub_account": AsyncSubAccountClient,
+    "sub_account_api_keys": AsyncSubAccountApiKeysClient,
+    "mining_pool": AsyncMiningPoolClient,
+    "credit_line": AsyncCreditLineClient,
+    "collateral_trading": AsyncCollateralTradingClient,
+    "market_fee": AsyncMarketFeeClient,
+    "spot_trading": AsyncSpotTradingClient,
+}
+
+_TOP_LEVEL_METHODS = ("convert_estimate", "convert_confirm", "convert_history")
+
+# Credential parameters injected into every tool signature.
+_CRED_PARAMS = [
+    inspect.Parameter("api_key", kind=inspect.Parameter.KEYWORD_ONLY, annotation=str),
+    inspect.Parameter("secret_key", kind=inspect.Parameter.KEYWORD_ONLY, annotation=str),
+]
+
+# secret_key as optional — for endpoints that don't use HMAC signing.
+_SECRET_KEY_OPTIONAL = inspect.Parameter(
+    "secret_key",
+    kind=inspect.Parameter.KEYWORD_ONLY,
+    annotation=str,
+    default="",
+)
+
+# Extra bearer_token parameter injected into account_endpoints tools.
+_BEARER_PARAM = inspect.Parameter(
+    "bearer_token",
+    kind=inspect.Parameter.KEYWORD_ONLY,
+    annotation=str,
+    default="",
+)
+
+# HMAC signing fields injected by the transport — stripped from SDK method params.
+_HMAC_FIELDS = {"request", "nonce"}
+
+# SDK sends these snake_case keys but WhiteBit API expects camelCase.
+_SNAKE_TO_CAMEL = {
+    "order_id": "orderId",
+    "client_order_id": "clientOrderId",
+}
+
+_ENV = None
+
+
+def _get_environment() -> WhitebitApiEnvironment:
+    global _ENV
+    if _ENV is None:
+        base_url = os.environ.get("WHITEBIT_BASE_URL", "https://whitebit.com")
+        _ENV = WhitebitApiEnvironment(
+            base=base_url,
+            production=WhitebitApiEnvironment.DEFAULT.production,
+            eu=WhitebitApiEnvironment.DEFAULT.eu,
+        )
+    return _ENV
+
+
+def _is_credentials_error(exc: Exception) -> bool:
+    msg = str(exc).lower()
+    return "invalid payload" in msg or "code: 9" in msg
+
+
+class WhitebitHmacTransport(httpx.AsyncBaseTransport):
+    """Signs POST requests with WhiteBit HMAC-SHA512."""
+
+    def __init__(self, api_key: str, secret_key: str):
+        self._api_key = api_key
+        self._secret_key = secret_key
+        self._inner = httpx.AsyncHTTPTransport()
+
+    @staticmethod
+    def _ua_for(request: httpx.Request) -> bytes:
+        existing = request.headers.get("user-agent", "")
+        return (f"{existing} mcp/python" if existing else "mcp/python").encode()
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        if request.method == "POST":
+            try:
+                body_bytes = request.content
+            except httpx.RequestNotRead:
+                body_bytes = b""
+
+            body_dict = {}
+            if body_bytes:
+                try:
+                    body_dict = json.loads(body_bytes)
+                except (json.JSONDecodeError, ValueError):
+                    pass
+
+            # Rename snake_case keys that WhiteBit API expects as camelCase.
+            for snake, camel in _SNAKE_TO_CAMEL.items():
+                if snake in body_dict:
+                    body_dict[camel] = body_dict.pop(snake)
+
+            body_dict["request"] = request.url.path
+            body_dict["nonce"] = time.time_ns()
+
+            new_body = json.dumps(body_dict, separators=(',', ':')).encode()
+            payload = base64.b64encode(new_body).decode()
+            signature = _hmac.new(
+                self._secret_key.encode(), payload.encode(), hashlib.sha512
+            ).hexdigest()
+
+            new_headers = [
+                (k, v) for k, v in request.headers.raw
+                if k.lower() not in (
+                    b"authorization", b"content-type", b"content-length",
+                    b"x-txc-apikey", b"x-txc-payload", b"x-txc-signature",
+                    b"user-agent",
+                )
+            ]
+            new_headers += [
+                (b"x-txc-apikey", self._api_key.encode()),
+                (b"x-txc-payload", payload.encode()),
+                (b"x-txc-signature", signature.encode()),
+                (b"content-type", b"application/json"),
+                (b"content-length", str(len(new_body)).encode()),
+                (b"user-agent", self._ua_for(request)),
+            ]
+            request = httpx.Request(
+                method=request.method,
+                url=request.url,
+                headers=new_headers,
+                content=new_body,
+                extensions=request.extensions,
+            )
+
+        else:
+            new_headers = [(k, v) for k, v in request.headers.raw if k.lower() != b"user-agent"]
+            new_headers.append((b"user-agent", self._ua_for(request)))
+            try:
+                body = request.content
+            except httpx.RequestNotRead:
+                body = b""
+            request = httpx.Request(
+                method=request.method,
+                url=request.url,
+                headers=new_headers,
+                content=body,
+                extensions=request.extensions,
+            )
+
+        return await self._inner.handle_async_request(request)
+
+    async def aclose(self):
+        await self._inner.aclose()
+
+
+class _NoAuthClientWrapper(AsyncClientWrapper):
+    """AsyncClientWrapper that omits the Authorization header (for OAuth2 exchange endpoints)."""
+
+    def get_headers(self) -> dict:
+        return {"X-Fern-Language": "Python", "X-TXC-APIKEY": self._txc_apikey}
+
+
+mcp = FastMCP("whitebit-mcp", host="0.0.0.0", port=8000)
+
+
+def _make_tool(subclient_attr: str | None, method_name: str, original_sig: inspect.Signature):
+    is_account_endpoint = subclient_attr == "account_endpoints"
+    is_authentication = subclient_attr == "authentication"
+
+    orig_params = [
+        p.replace(kind=inspect.Parameter.KEYWORD_ONLY, default=None)
+        if p.default is OMIT
+        else p.replace(kind=inspect.Parameter.KEYWORD_ONLY)
+        for name, p in original_sig.parameters.items()
+        if name not in ("self", "request_options") and name not in _HMAC_FIELDS
+    ]
+    # Remember which HMAC fields the method needs so we can inject dummies.
+    needs_hmac_fields = {
+        name for name in original_sig.parameters
+        if name in _HMAC_FIELDS
+    }
+
+    # HMAC endpoints need api_key + secret_key.
+    # authentication only needs api_key; account_endpoints need api_key + bearer_token.
+    _api_key_param = _CRED_PARAMS[0]
+    if is_account_endpoint:
+        new_sig = original_sig.replace(parameters=[_api_key_param, _SECRET_KEY_OPTIONAL, _BEARER_PARAM] + orig_params)
+    elif is_authentication:
+        new_sig = original_sig.replace(parameters=[_api_key_param, _SECRET_KEY_OPTIONAL] + orig_params)
+    else:
+        new_sig = original_sig.replace(parameters=_CRED_PARAMS + orig_params)
+
+    async def tool(**kwargs):
+        api_key = kwargs.pop("api_key")
+        secret_key = kwargs.pop("secret_key", "")
+        bearer_token = kwargs.pop("bearer_token", "")
+
+        needs_hmac = not is_authentication and not is_account_endpoint
+        if not api_key or (needs_hmac and not secret_key):
+            raise RuntimeError(
+                "❌ api_key and secret_key must be provided as tool parameters."
+                if needs_hmac else
+                "❌ api_key must be provided as tool parameter."
+            )
+        if is_account_endpoint and not bearer_token:
+            raise RuntimeError(
+                "❌ account_endpoints require a bearer_token (OAuth2 access token). "
+                "Obtain one via authentication__get_access_token first."
+            )
+
+        cleaned = {k: v for k, v in kwargs.items() if v is not None}
+        # Inject dummy values for HMAC signing fields — transport overwrites them.
+        for field in needs_hmac_fields:
+            cleaned.setdefault(field, "auto")
+
+        try:
+            if subclient_attr is None:
+                transport = WhitebitHmacTransport(api_key=api_key, secret_key=secret_key)
+                async with httpx.AsyncClient(transport=transport) as hmac_client:
+                    obj = AsyncWhitebitApi(
+                        txc_apikey=api_key, token="unused",
+                        environment=_get_environment(), httpx_client=hmac_client,
+                    )
+                    return await getattr(obj, method_name)(**cleaned)
+            elif is_account_endpoint:
+                async with httpx.AsyncClient() as plain_client:
+                    wrapper = AsyncClientWrapper(
+                        txc_apikey=api_key, token=bearer_token,
+                        environment=_get_environment(), httpx_client=plain_client,
+                    )
+                    obj = AsyncAccountEndpointsClient(client_wrapper=wrapper)
+                    return await getattr(obj, method_name)(**cleaned)
+            elif is_authentication:
+                async with httpx.AsyncClient() as plain_client:
+                    wrapper = _NoAuthClientWrapper(
+                        txc_apikey=api_key, token="unused",
+                        environment=_get_environment(), httpx_client=plain_client,
+                    )
+                    obj = AsyncAuthenticationClient(client_wrapper=wrapper)
+                    return await getattr(obj, method_name)(**cleaned)
+            else:
+                transport = WhitebitHmacTransport(api_key=api_key, secret_key=secret_key)
+                async with httpx.AsyncClient(transport=transport) as hmac_client:
+                    wrapper = AsyncClientWrapper(
+                        txc_apikey=api_key, token="unused",
+                        environment=_get_environment(), httpx_client=hmac_client,
+                    )
+                    subclient_cls = SUBCLIENT_CLASSES[subclient_attr]
+                    obj = subclient_cls(client_wrapper=wrapper)
+                    return await getattr(obj, method_name)(**cleaned)
+        except RuntimeError:
+            raise
+        except Exception as exc:
+            if _is_credentials_error(exc):
+                raise RuntimeError(
+                    f"❌ WhiteBit API auth/request error: {exc}"
+                ) from None
+            raise
+
+    tool.__name__ = method_name
+    tool.__signature__ = new_sig
+    return tool
+
+
+def register_whitebit_tools():
+    for name in _TOP_LEVEL_METHODS:
+        method = getattr(AsyncWhitebitApi, name)
+        fn = _make_tool(None, name, inspect.signature(method))
+        fn.__doc__ = method.__doc__
+        mcp.tool(name=name, description=(method.__doc__ or "").strip().split("\n")[0])(fn)
+
+    for attr_name, subclient_cls in SUBCLIENT_CLASSES.items():
+        for method_name, method in inspect.getmembers(subclient_cls, predicate=inspect.isfunction):
+            if method_name.startswith("_"):
+                continue
+            tool_name = f"{attr_name}__{method_name}"
+            fn = _make_tool(attr_name, method_name, inspect.signature(method))
+            fn.__doc__ = method.__doc__
+            description = (method.__doc__ or "").strip().split("\n")[0]
+            mcp.tool(name=tool_name, description=description)(fn)
+
+
+register_whitebit_tools()
+
+
+@mcp.tool(
+    name="get_credentials_status",
+    description="Check whether WhiteBit API credentials are valid by echoing masked values.",
+)
+async def get_credentials_status(api_key: str, secret_key: str) -> str:
+    base_url = os.environ.get("WHITEBIT_BASE_URL", "https://whitebit.com")
+    if api_key and secret_key:
+        masked_key = api_key[:4] + "****" + api_key[-4:] if len(api_key) > 8 else "****"
+        masked_secret = "****" + secret_key[-4:] if len(secret_key) > 4 else "****"
+        return (
+            f"✅ Credentials provided.\n"
+            f"   API key:    {masked_key}\n"
+            f"   Secret key: {masked_secret}\n"
+            f"   Base URL:   {base_url}"
+        )
+    return "❌ api_key and/or secret_key not provided."
+
+
+if __name__ == "__main__":
+    mcp.run(transport="streamable-http")