{"id":32675595,"url":"https://github.com/danishashko/binance-mcp-server","last_synced_at":"2026-05-18T14:35:05.376Z","repository":{"id":320755367,"uuid":"1083238310","full_name":"danishashko/binance-mcp-server","owner":"danishashko","description":"MCP server for Binance API. Access real-time crypto prices, order books, historical data, and trading pairs","archived":false,"fork":false,"pushed_at":"2025-10-25T16:16:51.000Z","size":35,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-25T18:28:27.867Z","etag":null,"topics":["ai","binance","claude","crypto","mcp","python"],"latest_commit_sha":null,"homepage":"https://www.linkedin.com/in/daniel-shashko/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danishashko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-25T16:07:58.000Z","updated_at":"2025-10-25T16:19:03.000Z","dependencies_parsed_at":"2025-10-25T18:28:29.853Z","dependency_job_id":"f98dcbf4-85d9-4287-a64c-8cbb46b6da78","html_url":"https://github.com/danishashko/binance-mcp-server","commit_stats":null,"previous_names":["danishashko/binance-mcp-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/danishashko/binance-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danishashko%2Fbinance-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danishashko%2Fbinance-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danishashko%2Fbinance-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danishashko%2Fbinance-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danishashko","download_url":"https://codeload.github.com/danishashko/binance-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danishashko%2Fbinance-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33181155,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T09:27:30.708Z","status":"ssl_error","status_checked_at":"2026-05-18T09:27:28.300Z","response_time":71,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","binance","claude","crypto","mcp","python"],"created_at":"2025-11-01T06:01:44.079Z","updated_at":"2026-05-18T14:35:05.364Z","avatar_url":"https://github.com/danishashko.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eBinance MCP Server\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.python.org/downloads/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.10%2B-blue.svg\" alt=\"Python Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-green.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://modelcontextprotocol.io/\"\u003e\u003cimg src=\"https://img.shields.io/badge/MCP-compatible-purple.svg\" alt=\"MCP\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.binance.com/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Binance-API-yellow.svg\" alt=\"Binance API\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/status-active-success.svg\" alt=\"Status\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg\" alt=\"Platform\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg width=\"1032\" height=\"879\" alt=\"image\" src=\"https://github.com/user-attachments/assets/6f00b820-11a4-4d01-ade9-96127852b3d0\" /\u003e\n\u003c/p\u003e\n\n---\n\nA Model Context Protocol (MCP) server that provides access to Binance's public Spot API, enabling LLMs to fetch real-time cryptocurrency market data, trading pairs information, and exchange statistics.\n\n## Features\n\n### 🎯 Core Capabilities\n\n- **Real-time Price Data**: Get current prices and 24-hour statistics for any trading pair\n- **Market Discovery**: Search and explore available trading pairs by asset or keyword\n- **Order Book Analysis**: Analyze market depth with bid/ask data\n- **Historical Data**: Retrieve candlestick/OHLC data for technical analysis\n- **Trade Flow**: View recent trades and market activity\n- **Exchange Information**: Access trading rules, rate limits, and symbol details\n\n### 🔧 Available Tools\n\n1. **binance_get_ticker** - Get current price and 24hr statistics\n2. **binance_search_symbols** - Find trading pairs by asset or keyword\n3. **binance_get_order_book** - Get order book depth (bids/asks)\n4. **binance_get_klines** - Get candlestick/OHLC data for charting\n5. **binance_get_recent_trades** - View recent executed trades\n6. **binance_get_exchange_info** - Get comprehensive exchange information\n7. **binance_get_price** - Quick price lookup (lightweight)\n8. **binance_get_best_price** - Get best bid/ask prices\n\n### ✨ Key Features\n\n- **No Authentication Required**: All endpoints use public API (no API keys needed)\n- **Dual Response Formats**: Both human-readable Markdown and machine-readable JSON\n- **Smart Truncation**: Automatically handles large responses with helpful guidance\n- **Actionable Errors**: Clear error messages that guide users to correct usage\n- **Rate Limit Aware**: Respects Binance API rate limits and provides guidance\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10 or higher\n- pip (Python package manager)\n\n### Setup\n\n1. **Clone or download this repository**\n\n2. **Install dependencies**:\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Verify installation**:\n   ```bash\n   python -m py_compile binance_mcp.py\n   ```\n\n## Usage\n\n### With Claude Desktop\n\nAdd this to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"binance\": {\n      \"command\": \"python\",\n      \"args\": [\"/absolute/path/to/binance_mcp.py\"]\n    }\n  }\n}\n```\n\nReplace `/absolute/path/to/binance_mcp.py` with the actual path to the file.\n\n### Testing\n\nYou can test the server using the MCP inspector or by calling tools directly:\n\n```python\n# Example: Get current Bitcoin price\nbinance_get_price(symbols=[\"BTCUSDT\"])\n\n# Example: Search for all BTC trading pairs\nbinance_search_symbols(base_asset=\"BTC\")\n\n# Example: Get 24hr statistics\nbinance_get_ticker(symbols=[\"BTCUSDT\", \"ETHUSDT\"])\n\n# Example: Get hourly candlestick data\nbinance_get_klines(symbol=\"BTCUSDT\", interval=\"1h\", limit=24)\n```\n\n## Tool Details\n\n### binance_get_ticker\n\nGet current price and 24-hour trading statistics.\n\n**Parameters**:\n- `symbols`: List of trading pair symbols (required)\n- `type`: \"FULL\" or \"MINI\" (default: \"FULL\")\n- `response_format`: \"markdown\" or \"json\" (default: \"markdown\")\n\n**Example**:\n```python\nbinance_get_ticker(symbols=[\"BTCUSDT\", \"ETHUSDT\"], type=\"FULL\")\n```\n\n**Returns**: Current price, 24h change %, high/low, volume, bid/ask, etc.\n\n---\n\n### binance_search_symbols\n\nFind trading pairs by filtering on base asset, quote asset, or keyword.\n\n**Parameters**:\n- `base_asset`: Base currency filter (e.g., \"BTC\")\n- `quote_asset`: Quote currency filter (e.g., \"USDT\")\n- `search_term`: Keyword to search in symbol names\n- `status`: \"TRADING\" or \"ALL\" (default: \"TRADING\")\n- `response_format`: \"markdown\" or \"json\" (default: \"markdown\")\n\n**Example**:\n```python\n# Find all BTC pairs\nbinance_search_symbols(base_asset=\"BTC\")\n\n# Find all USDT pairs\nbinance_search_symbols(quote_asset=\"USDT\")\n\n# Find specific pair\nbinance_search_symbols(base_asset=\"BTC\", quote_asset=\"USDT\")\n\n# Search by keyword\nbinance_search_symbols(search_term=\"DOGE\")\n```\n\n**Returns**: List of matching trading pairs with status and features.\n\n---\n\n### binance_get_order_book\n\nGet order book depth showing bids and asks.\n\n**Parameters**:\n- `symbol`: Trading pair symbol (required)\n- `limit`: Depth level - 5, 10, 20, 50, 100, 500, 1000, or 5000 (default: 100)\n- `response_format`: \"markdown\" or \"json\" (default: \"markdown\")\n\n**Example**:\n```python\nbinance_get_order_book(symbol=\"BTCUSDT\", limit=20)\n```\n\n**Returns**: Order book with prices, quantities, and spread analysis.\n\n---\n\n### binance_get_klines\n\nGet candlestick/OHLC data for technical analysis.\n\n**Parameters**:\n- `symbol`: Trading pair symbol (required)\n- `interval`: Time interval (required) - \"1m\", \"5m\", \"15m\", \"30m\", \"1h\", \"4h\", \"1d\", \"1w\", \"1M\"\n- `limit`: Number of candles (default: 100, max: 1000)\n- `start_time`: Optional start timestamp in milliseconds\n- `end_time`: Optional end timestamp in milliseconds\n- `response_format`: \"markdown\" or \"json\" (default: \"markdown\")\n\n**Example**:\n```python\n# Last 24 hours of hourly data\nbinance_get_klines(symbol=\"BTCUSDT\", interval=\"1h\", limit=24)\n\n# Last 30 days of daily data\nbinance_get_klines(symbol=\"ETHUSDT\", interval=\"1d\", limit=30)\n\n# Last year of weekly data\nbinance_get_klines(symbol=\"BNBUSDT\", interval=\"1w\", limit=52)\n```\n\n**Returns**: OHLC data with volume, trade count, and change percentages.\n\n---\n\n### binance_get_recent_trades\n\nGet recent executed trades for a symbol.\n\n**Parameters**:\n- `symbol`: Trading pair symbol (required)\n- `limit`: Number of trades (default: 100, max: 1000)\n- `response_format`: \"markdown\" or \"json\" (default: \"markdown\")\n\n**Example**:\n```python\nbinance_get_recent_trades(symbol=\"BTCUSDT\", limit=50)\n```\n\n**Returns**: Recent trades with price, quantity, time, and buy/sell side.\n\n---\n\n### binance_get_exchange_info\n\nGet comprehensive exchange information and trading rules.\n\n**Parameters**:\n- `symbols`: Optional list of specific symbols\n- `response_format`: \"markdown\" or \"json\" (default: \"markdown\")\n\n**Example**:\n```python\n# Get info for specific symbols\nbinance_get_exchange_info(symbols=[\"BTCUSDT\", \"ETHUSDT\"])\n\n# Get info for all symbols (large response)\nbinance_get_exchange_info()\n```\n\n**Returns**: Exchange timezone, rate limits, trading rules, symbol details.\n\n---\n\n### binance_get_price\n\nGet latest price only (lightweight, fast query).\n\n**Parameters**:\n- `symbols`: List of trading pair symbols (required)\n- `response_format`: \"markdown\" or \"json\" (default: \"markdown\")\n\n**Example**:\n```python\nbinance_get_price(symbols=[\"BTCUSDT\", \"ETHUSDT\", \"BNBUSDT\"])\n```\n\n**Returns**: Current price for each symbol.\n\n---\n\n### binance_get_best_price\n\nGet best bid/ask prices from the order book.\n\n**Parameters**:\n- `symbols`: List of trading pair symbols (required)\n- `response_format`: \"markdown\" or \"json\" (default: \"markdown\")\n\n**Example**:\n```python\nbinance_get_best_price(symbols=[\"BTCUSDT\"])\n```\n\n**Returns**: Best bid/ask prices with quantities and spread analysis.\n\n## Common Use Cases\n\n### 1. Check Current Cryptocurrency Prices\n\n```python\n# Simple price check\nbinance_get_price(symbols=[\"BTCUSDT\", \"ETHUSDT\"])\n\n# Detailed 24hr statistics\nbinance_get_ticker(symbols=[\"BTCUSDT\", \"ETHUSDT\"])\n```\n\n### 2. Find Trading Pairs\n\n```python\n# Find all Bitcoin pairs\nbinance_search_symbols(base_asset=\"BTC\")\n\n# Find all USDT pairs\nbinance_search_symbols(quote_asset=\"USDT\")\n\n# Search for specific coins\nbinance_search_symbols(search_term=\"DOGE\")\n```\n\n### 3. Technical Analysis\n\n```python\n# Get hourly data for last 24 hours\nbinance_get_klines(symbol=\"BTCUSDT\", interval=\"1h\", limit=24)\n\n# Get daily data for last 30 days\nbinance_get_klines(symbol=\"BTCUSDT\", interval=\"1d\", limit=30)\n```\n\n### 4. Market Depth Analysis\n\n```python\n# Check order book depth\nbinance_get_order_book(symbol=\"BTCUSDT\", limit=100)\n\n# Get best bid/ask\nbinance_get_best_price(symbols=[\"BTCUSDT\"])\n```\n\n### 5. Monitor Market Activity\n\n```python\n# View recent trades\nbinance_get_recent_trades(symbol=\"BTCUSDT\", limit=100)\n```\n\n## Error Handling\n\nThe server provides actionable error messages:\n\n### Invalid Symbol\n```\nError: Symbol 'BTCUSD' not found on Binance.\n\nDid you mean: BTCUSDT, BTCBUSD, BTCUSDC?\n\nTo find valid trading pairs, use the 'binance_search_symbols' tool:\n- Search by base asset: binance_search_symbols(base_asset=\"BTC\")\n- Search by quote asset: binance_search_symbols(quote_asset=\"USDT\")\n```\n\n### Rate Limit\n```\nError: Rate limit exceeded (HTTP 429)\n\nBinance rate limit: 6000 request weight per minute\n\nAction: Wait 60 seconds before making more requests.\nTip: Use multiple symbols in one request instead of separate requests.\n```\n\n### Response Too Large\n```\nResponse truncated: Showing 50 of 200 symbols\n\nThe full response exceeds the 25,000 character limit.\n\nTo get more specific results:\n- Filter by asset: binance_search_symbols(base_asset=\"BTC\")\n- Request fewer symbols: binance_get_ticker(symbols=[\"BTCUSDT\", \"ETHUSDT\"])\n```\n\n## Rate Limits\n\nBinance API rate limits:\n- **Request Weight**: 6,000 per minute\n- **Raw Requests**: 61,000 per 5 minutes\n\nThe server respects these limits and provides guidance when limits are approached.\n\n## Response Formats\n\n### Markdown (Default)\nHuman-readable format with:\n- Headers and sections\n- Tables for structured data\n- Emojis for visual indicators\n- Human-readable timestamps\n- Formatted numbers with currency symbols\n\n### JSON\nMachine-readable format with:\n- Complete field data\n- Consistent structure\n- Numeric timestamps\n- All metadata included\n\n## Technical Details\n\n### Architecture\n- **Language**: Python 3.10+\n- **Framework**: FastMCP (MCP Python SDK)\n- **HTTP Client**: httpx (async)\n- **Validation**: Pydantic v2\n- **Transport**: stdio\n\n### API Endpoint\n- **Base URL**: `https://data-api.binance.vision`\n- **Public API**: No authentication required\n\n### Character Limit\n- Maximum response size: 25,000 characters\n- Automatic truncation with guidance when exceeded\n\n## Troubleshooting\n\n### Server won't start\n- Check Python version: `python --version` (must be 3.10+)\n- Verify dependencies: `pip list | grep -E \"fastmcp|httpx|pydantic\"`\n- Test syntax: `python -m py_compile binance_mcp.py`\n\n### Connection errors\n- Check internet connection\n- Verify Binance API is accessible: `curl https://api.binance.com/api/v3/ping`\n\n### Symbol not found\n- Use `binance_search_symbols` to find valid trading pairs\n- Ensure symbol is in correct format (e.g., \"BTCUSDT\" not \"BTC-USDT\")\n\n## Contributing\n\nSuggestions and improvements are welcome! This MCP server follows the MCP best practices for:\n- Tool naming with service prefix\n- Comprehensive documentation\n- Actionable error messages\n- Response format flexibility\n- Smart truncation with guidance\n\n## License\n\nMIT License - feel free to use and modify as needed.\n\n## Resources\n\n- [Binance API Documentation](https://developers.binance.com/docs/binance-spot-api-docs)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [FastMCP Documentation](https://github.com/modelcontextprotocol/python-sdk)\n\n## Version History\n\n### v1.0.0 (Initial Release)\n- 8 comprehensive tools for Binance Spot API\n- Public API endpoints (no authentication)\n- Dual response formats (Markdown/JSON)\n- Smart truncation and error handling\n- Complete documentation\n\n---\n\n**Happy Trading! 🚀📈**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanishashko%2Fbinance-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanishashko%2Fbinance-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanishashko%2Fbinance-mcp-server/lists"}