# Binance MCP Server

A comprehensive FastMCP server implementation providing datetime utilities and Binance API integration tools for cryptocurrency market operations.

## Features

- 🕒 **DateTime Tools**: Get current date and time in ISO8601 format
- 📈 **Binance API Integration**: Direct connectivity to Binance cryptocurrency exchange
- 🔄 **Connectivity Testing**: Test Binance API connectivity and server time sync
- 🚀 **FastMCP Framework**: Built with FastMCP for efficient MCP server implementation
- ⚙️ **Configuration Management**: Environment-based configuration with dotenv support
- 📊 **Observability**: Logfire integration for monitoring and debugging

## Installation

### Requirements
- Python 3.8+
- Dependencies listed in `pyproject.toml`

### Setup
```bash
# Install dependencies using rye (recommended)
rye sync

# Or using uv
uv sync
```

### Environment Configuration

Create a `.env` file in the project root:

```env
# Server Configuration
PORT=8000
TRANSPORT=http

# Binance API Credentials (optional for basic tools)
BINANCE_API_KEY=your_api_key_here
BINANCE_API_SECRET=your_api_secret_here

# Observability (optional)
LOGFIRE_TOKEN=your_logfire_token_here
```

**Note**: API credentials are only required for authenticated Binance operations. Basic tools like datetime and connectivity testing work without credentials.

## Usage

### Running the Server

#### Standalone Mode
```bash
# Run the server directly
python -m binance_mcp.main

# Or use the installed script
mcp

# For development (from project root)
python -m src.binance_mcp.main
```

#### With MCP Client (e.g., Claude Desktop)

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "binance-mcp": {
      "command": "python",
      "args": ["-m", "binance_mcp.main"],
      "cwd": "/path/to/binance-mcp",
      "env": {
        "BINANCE_API_KEY": "your_api_key",
        "BINANCE_API_SECRET": "your_api_secret"
      }
    }
  }
}
```

## Available Tools

### `get_current_datetime`

Returns the current date and time in ISO8601 format.

**Parameters:** None

**Response:**
- `timestamp` (string): Current date and time in ISO8601 format

**Example Response:**
```json
{
  "timestamp": "2025-08-18T23:01:41.949232+00:00"
}
```

### `binance_test_connectivity`

Tests connectivity to the Binance API endpoints.

**Parameters:** None

**Response:**
- `timestamp` (string): ISO8601 timestamp when the test was performed
- `reachable` (boolean): True if Binance API is reachable, False otherwise

**Example Response:**
```json
{
  "timestamp": "2025-08-18T23:01:41.949232+00:00",
  "reachable": true
}
```

### `get_binance_server_time`

Retrieves the current server time from Binance.

**Parameters:** None

**Response:**
- `server_time` (integer): Unix timestamp in milliseconds representing Binance server time

**Example Response:**
```json
{
  "server_time": 1692396701949
}
```

## Development

### Project Structure
```
binance-mcp/
├── src/
│   └── binance_mcp/
│       ├── __init__.py
│       ├── main.py           # Main MCP server implementation
│       ├── models.py         # Pydantic response models
│       ├── settings.py       # Configuration management
│       ├── client.py         # Binance client factory
│       └── tools/
│           ├── __init__.py
│           └── timestamp.py  # DateTime and Binance time tools
├── pyproject.toml            # Project configuration
├── .env                      # Environment variables (create from template)
└── README.md                # This file
```

### Testing

Test the server functionality:
```bash
# Test individual tools (requires server to be running)
# The FastMCP framework provides built-in testing capabilities

# Run the server in development mode
rye run mcp

# Or if the virtualenv is activated
mcp

# Or use ruff for code quality checks
rye run ruff check src/
```

## Future Enhancements

- [ ] Market data tools (ticker prices, order book, candlestick data)
- [ ] Account information tools (balances, trading history)
- [ ] Trading operations (place orders, cancel orders)
- [ ] WebSocket streaming tools for real-time data
- [ ] Additional cryptocurrency exchange integrations
- [ ] Rate limiting and advanced error handling
- [ ] Caching mechanisms for frequently accessed data
- [ ] Portfolio analytics and reporting tools

## License

[Add your license here]

## Contributing

[Add contribution guidelines if needed]