binance-futures-mcp 1.0.0__tar.gz

binance_futures_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Binance MCP Server
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

binance_futures_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,437 @@
+Metadata-Version: 2.4
+Name: binance-futures-mcp
+Version: 1.0.0
+Summary: A Model Context Protocol server for Binance Futures API
+Author: Binance MCP Server
+License: MIT
+Project-URL: Homepage, https://github.com/bin-mcp/binance-mcp-server
+Project-URL: Repository, https://github.com/bin-mcp/binance-mcp-server.git
+Project-URL: Issues, https://github.com/bin-mcp/binance-mcp-server/issues
+Keywords: mcp,binance,trading,futures,api,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# Binance MCP Server
+
+A Model Context Protocol (MCP) server that provides comprehensive access to Binance Futures API endpoints. This server implements all major trading, account management, and market data functionality as documented in the Binance Futures API.
+
+## Features
+
+### Account Information Tools
+- Get account info, balance, and position information
+- Query position mode and commission rates
+- Access risk management data (ADL quantile, leverage brackets, force orders)
+
+### Order Management Tools
+- Place orders (MARKET, LIMIT, STOP, STOP_MARKET, TRAILING_STOP_MARKET)
+- Place multiple orders in batch
+- Cancel orders (single, multiple, or all)
+- Query order status and history
+- Auto-cancel functionality
+
+### Trading Configuration Tools
+- Change leverage and margin type
+- Switch between hedge and one-way position modes
+- Modify position margins
+
+### Market Data Tools
+- Get exchange information and trading rules
+- Access real-time price data and order books
+- Retrieve candlestick/kline data
+- Get mark prices and funding rates
+- Access aggregate trade data
+
+### Trading History Tools
+- Get account trade history
+- Access income history (funding fees, PnL, etc.)
+- Retrieve funding rate history
+
+## Installation
+
+### Prerequisites
+- Python 3.8 or higher
+- Binance Futures API credentials
+
+### Method 1: Install via uvx (Recommended)
+
+```bash
+uvx --from git+https://github.com/alexcandrabersiva/bin-mcp binance-mcp-server
+```
+
+### Method 2: Local Installation
+
+```bash
+cd binance-mcp-server
+pip install -e .
+```
+
+Or install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## MCP Client Configuration
+
+This server can be integrated with various MCP clients. Here are configuration examples for popular clients:
+
+### VS Code
+
+Add to your VS Code `settings.json`:
+
+```json
+{
+  "mcp.servers": {
+    "binance": {
+      "command": "uvx",
+      "args": ["binance-mcp-server"],
+      "env": {
+        "BINANCE_API_KEY": "your_api_key_here",
+        "BINANCE_SECRET_KEY": "your_secret_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor configuration file (`.cursor/mcp.json`):
+
+```json
+{
+  "servers": {
+    "binance": {
+      "command": "uvx",
+      "args": ["binance-mcp-server"],
+      "env": {
+        "BINANCE_API_KEY": "your_api_key_here",
+        "BINANCE_SECRET_KEY": "your_secret_key_here"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to your Windsurf configuration (`.windsurf/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "binance": {
+      "command": "uvx",
+      "args": ["binance-mcp-server"],
+      "env": {
+        "BINANCE_API_KEY": "your_api_key_here",
+        "BINANCE_SECRET_KEY": "your_secret_key_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+**On macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**On Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "binance": {
+      "command": "uvx",
+      "args": ["binance-mcp-server"],
+      "env": {
+        "BINANCE_API_KEY": "your_api_key_here",
+        "BINANCE_SECRET_KEY": "your_secret_key_here"
+      }
+    }
+  }
+}
+```
+
+### Configuration Notes
+
+1. **No path needed**: With PyPI installation, you don't need to specify paths or working directories.
+
+2. **Set API credentials**: Replace `your_api_key_here` and `your_secret_key_here` with your actual Binance API credentials.
+
+3. **Alternative commands**: You can also use:
+   - `pip install binance-mcp-server && python -m binance_mcp`
+   - `binance-mcp-server` (if installed globally)
+
+4. **Python environment**: Using `uvx` automatically handles the Python environment.
+
+5. **Security**: For production use, consider storing credentials in your system's environment variables instead of directly in configuration files.
+
+## Installation
+
+### Prerequisites
+- Python 3.8 or higher
+- Binance Futures API credentials
+
+### Method 1: Install via uvx (Recommended)
+
+```bash
+uvx --from git+https://github.com/alexcandrabersiva/bin-mcp binance-mcp-server
+```
+
+### Method 2: Local Installation
+
+```bash
+cd binance-mcp-server
+pip install -e .
+```
+
+Or install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Configuration
+
+### Environment Variables
+
+Set your Binance API credentials as environment variables:
+
+```bash
+export BINANCE_API_KEY="your_api_key_here"
+export BINANCE_SECRET_KEY="your_secret_key_here"
+```
+
+### API Permissions
+
+Your Binance API key needs the following permissions:
+- **Futures Trading**: For order placement and management
+- **Futures Reading**: For account and market data access
+
+**Note**: Market data endpoints (exchange info, prices, order books, etc.) work without authentication.
+
+## Usage
+
+### Running the Server
+
+```bash
+# Run directly
+python -m binance_mcp
+
+# Or using the installed script
+binance-mcp-server
+```
+
+### Available Tools
+
+The server provides 32 tools organized into categories:
+
+#### Account Information (5 tools)
+- `get_account_info` - Get futures account information
+- `get_balance` - Get account balance for all assets
+- `get_position_info` - Get current position information
+- `get_position_mode` - Get position mode (Hedge/One-way)
+- `get_commission_rate` - Get commission rate for a symbol
+
+#### Risk Management (4 tools)
+- `get_adl_quantile` - Get ADL quantile estimation
+- `get_leverage_brackets` - Get leverage brackets
+- `get_force_orders` - Get liquidation orders
+- `get_position_margin_history` - Get margin change history
+
+#### Order Management (10 tools)
+- `place_order` - Place a futures order
+- `place_multiple_orders` - Place multiple orders in batch
+- `cancel_order` - Cancel an active order
+- `cancel_multiple_orders` - Cancel multiple orders
+- `cancel_all_orders` - Cancel all open orders for a symbol
+- `auto_cancel_all_orders` - Set up auto-cancellation
+- `get_open_order` - Query specific open order
+- `get_open_orders` - Get all open orders
+- `get_all_orders` - Get all orders (filled, canceled, rejected)
+- `query_order` - Query order status
+
+#### Trading Configuration (4 tools)
+- `change_leverage` - Change initial leverage
+- `change_margin_type` - Change margin type (ISOLATED/CROSSED)
+- `change_position_mode` - Change position mode
+- `modify_position_margin` - Modify position margin
+
+#### Market Data (6 tools)
+- `get_exchange_info` - Get trading rules and symbol info
+- `get_book_ticker` - Get best bid/ask prices
+- `get_price_ticker` - Get latest prices
+- `get_order_book` - Get order book depth
+- `get_klines` - Get candlestick data
+- `get_mark_price` - Get mark price and funding rate
+- `get_aggregate_trades` - Get aggregate trade data
+
+#### Trading History (3 tools)
+- `get_account_trades` - Get account trade history
+- `get_income_history` - Get income history
+- `get_funding_rate_history` - Get funding rate history
+
+## Example Usage
+
+### Place a Market Order
+
+```json
+{
+  "tool": "place_order",
+  "arguments": {
+    "symbol": "BTCUSDT",
+    "side": "BUY",
+    "order_type": "MARKET",
+    "quantity": 0.001
+  }
+}
+```
+
+### Place a Limit Order
+
+```json
+{
+  "tool": "place_order",
+  "arguments": {
+    "symbol": "BTCUSDT",
+    "side": "BUY",
+    "order_type": "LIMIT",
+    "quantity": 0.001,
+    "price": 50000.0,
+    "time_in_force": "GTC"
+  }
+}
+```
+
+### Get Account Information
+
+```json
+{
+  "tool": "get_account_info",
+  "arguments": {}
+}
+```
+
+### Get Market Data
+
+```json
+{
+  "tool": "get_klines",
+  "arguments": {
+    "symbol": "BTCUSDT",
+    "interval": "1h",
+    "limit": 100
+  }
+}
+```
+
+## Security
+
+### API Key Security
+- Store API credentials securely using environment variables
+- Never commit credentials to version control
+- Use API keys with minimal required permissions
+- Consider using testnet for development
+
+### Rate Limiting
+The server respects Binance's rate limits:
+- Weight-based limits for different endpoints
+- Order placement rate limits
+- Automatic signature generation for authenticated requests
+
+### Error Handling
+- Comprehensive error handling for API failures
+- Clear error messages for common issues
+- Validation of required parameters
+
+## API Reference
+
+This server implements all endpoints documented in the Binance Futures API:
+
+- **Base URL**: `https://fapi.binance.com`
+- **API Type**: Binance USD-S Margined Futures
+- **Authentication**: API Key + HMAC SHA256 Signature
+
+For detailed parameter specifications, see the [Binance Futures API Documentation](https://binance-docs.github.io/apidocs/futures/en/).
+
+## Development
+
+### Project Structure
+
+```
+binance-mcp-server/
+├── src/
+│   └── binance_mcp/
+│       ├── __init__.py
+│       ├── __main__.py
+│       └── server.py
+├── pyproject.toml
+└── README.md
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Formatting
+
+```bash
+black src/
+ruff check src/
+```
+
+## Error Codes
+
+Common Binance API error codes:
+- `-1121`: Invalid symbol
+- `-2019`: Margin is insufficient  
+- `-1116`: Invalid orderType
+- `-1013`: Filter failure (PRICE_FILTER, LOT_SIZE, etc.)
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Disclaimer
+
+This software is for educational and development purposes. Trading cryptocurrencies involves substantial risk. Use at your own risk and never trade with money you cannot afford to lose.
+
+## Support
+
+For issues and questions:
+- Check the [Binance API Documentation](https://binance-docs.github.io/apidocs/futures/en/)
+- Review the error codes in the API documentation
+- Ensure your API credentials have the correct permissions