# Monta MCP Server

An MCP (Model Context Protocol) server that wraps the [Monta Python SDK](https://github.com/nickknissen/monta-python/) to provide LLM-friendly access to the Monta EV charging API.

## Features

This MCP server exposes the following tools for interacting with Monta's EV charging platform:

### Architecture Highlights
- **Efficient session management**: Uses FastMCP's lifespan pattern to maintain a single persistent aiohttp session
- **Connection pooling**: Reuses HTTP connections across all tool invocations for optimal performance
- **Type-safe context**: All tools access shared resources through strongly-typed lifespan context
- **Proper cleanup**: Automatically closes sessions on server shutdown
- **Robust error handling**: State-changing operations include input validation, timeout protection (10s), and comprehensive error logging

### Charge Point Management
- `get_charge_points` - List all available charging stations with pagination
- `get_charge_point` - Get detailed information about a specific charging station

### Charging Operations
- `get_charges` - View charging history/sessions with filtering options
- `start_charge` - Start a charging session at a specific charge point
- `stop_charge` - Stop an active charging session

### Wallet & Payments
- `get_personal_wallet` - View wallet balance and payment information
- `get_wallet_transactions` - Get transaction history with filtering

## Prerequisites

- Python 3.11 or higher
- Monta API credentials (client ID and client secret)
- `uv` package manager (recommended) or `pip`

## Installation

### Using uv (recommended)

```bash
git clone <repository-url>
cd monta-mcp
uv sync
```

### Using pip

```bash
git clone <repository-url>
cd monta-mcp
pip install -e .
```

## Configuration

The server requires Monta API credentials set as environment variables:

```bash
export MONTA_CLIENT_ID="your_client_id"
export MONTA_CLIENT_SECRET="your_client_secret"
```

### Getting Monta public API Credentials

Visit [Monta Public API Portal](https://docs.public-api.monta.com/reference/home#getting-access) and follow the guide

## Usage

### Running the Server

The server can be run directly:

```bash
# Using the installed script (default log: ./monta-mcp.log)
monta-mcp

# With custom log file location
monta-mcp --log-file /path/to/custom.log

# With custom log level
monta-mcp --log-level DEBUG

# Or using Python module
python -m monta_mcp
```

**Command-line Options:**
- `--log-file PATH` - Path to log file (default: `./monta-mcp.log`)
- `--log-level LEVEL` - Logging level: DEBUG, INFO, WARNING, ERROR (default: INFO)

### Testing with MCP Inspector

You can test the server using the MCP Inspector tool:

```bash
npx @modelcontextprotocol/inspector monta-mcp
```

This will open a web interface where you can:
- View all available tools
- Test tool calls with different parameters
- See responses from the Monta API

### Integrating with Claude Desktop

Add this configuration to your Claude Desktop config file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "monta": {
      "command": "monta-mcp",
      "env": {
        "MONTA_CLIENT_ID": "your_client_id",
        "MONTA_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

Or if using uv:

```json
{
  "mcpServers": {
    "monta": {
      "command": "uv",
      "args": ["run", "monta-mcp"],
      "env": {
        "MONTA_CLIENT_ID": "your_client_id",
        "MONTA_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

**With custom log location:**
```json
{
  "mcpServers": {
    "monta": {
      "command": "uv",
      "args": ["run", "monta-mcp", "--log-file", "/Users/you/logs/monta.log"],
      "env": {
        "MONTA_CLIENT_ID": "your_client_id",
        "MONTA_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

After adding the configuration, restart Claude Desktop. The Monta tools will be available in your conversations.

## Example Usage in Claude

Once configured, you can ask Claude things like:

- "Show me all my charging points"
- "Get details for charge point 12345"
- "What's my recent charging history?"
- "Check my wallet balance"
- "Start charging at station 12345"