adjust_isolated_margin

Add or remove margin from isolated positions on Binance Futures to manage risk exposure and optimize capital allocation for open trades.

Instructions

Add or remove margin from an isolated position.

Only valid when the symbol is in ISOLATED margin mode with an open position.

Input Schema

TableJSON Schema

Name	Required	Description
`symbol`	Yes	Trading pair, e.g. 'BTCUSDT'
`amount`	Yes	Amount to add or remove
`direction`	Yes	'add' to increase margin, 'remove' to decrease
`position_side`	No	Required in Hedge Mode

Implementation Reference

src/mcp_binance_futures/server.py:695-720 (handler)

The main handler function for the 'adjust_isolated_margin' tool. It adds or removes margin from an isolated position by calling Binance's /fapi/v1/positionMargin endpoint. Uses @mcp.tool decorator for registration and accepts symbol, amount, direction, and optional position_side parameters.

@mcp.tool
async def adjust_isolated_margin(
    ctx: Context,
    symbol: Annotated[str, Field(description="Trading pair, e.g. 'BTCUSDT'")],
    amount: Annotated[float, Field(description="Amount to add or remove", gt=0)],
    direction: Annotated[
        Literal["add", "remove"],
        Field(description="'add' to increase margin, 'remove' to decrease"),
    ],
    position_side: Annotated[
        Literal["BOTH", "LONG", "SHORT"] | None, Field(description="Required in Hedge Mode")
    ] = None,
) -> dict:
    """Add or remove margin from an isolated position.

    Only valid when the symbol is in ISOLATED margin mode with an open position.
    """
    params = _strip_none(
        {
            "symbol": symbol,
            "amount": amount,
            "type": 1 if direction == "add" else 2,  # Binance: 1=add, 2=remove
            "positionSide": position_side,
        }
    )
    return await _client(ctx).post_signed("/fapi/v1/positionMargin", params)

src/mcp_binance_futures/server.py:698-706 (schema)

Input schema definition using Pydantic's Annotated with Field for parameter validation. Defines symbol (str), amount (float with gt=0), direction (Literal['add', 'remove']), and position_side (optional Literal['BOTH', 'LONG', 'SHORT']) with descriptive field annotations.

symbol: Annotated[str, Field(description="Trading pair, e.g. 'BTCUSDT'")],
amount: Annotated[float, Field(description="Amount to add or remove", gt=0)],
direction: Annotated[
    Literal["add", "remove"],
    Field(description="'add' to increase margin, 'remove' to decrease"),
],
position_side: Annotated[
    Literal["BOTH", "LONG", "SHORT"] | None, Field(description="Required in Hedge Mode")
] = None,

src/mcp_binance_futures/server.py:51-59 (helper)

Helper functions used by adjust_isolated_margin: _client() extracts the BinanceClient from the FastMCP lifespan context, and _strip_none() removes None values from dictionaries before sending to Binance API.

def _client(ctx: Context) -> BinanceClient:
    """Extract BinanceClient from lifespan context."""
    assert ctx.request_context is not None
    return cast(BinanceClient, ctx.request_context.lifespan_context["client"])


def _strip_none(d: dict[str, Any]) -> dict[str, Any]:
    """Remove keys whose value is None so they are not sent to Binance."""
    return {k: v for k, v in d.items() if v is not None}

src/mcp_binance_futures/server.py:33-42 (registration)

FastMCP server instance creation that provides the @mcp.tool decorator mechanism. Tools decorated with @mcp.tool are automatically registered with the MCP server.

mcp = FastMCP(
    name="Binance Futures",
    instructions=(
        "Tools for Binance USDT-M Futures: market data, account balances, "
        "open positions, order placement/modification/cancellation, leverage "
        "and margin-type control. Most tools accept a `symbol` parameter "
        "(e.g. 'BTCUSDT') to scope the operation to one instrument."
    ),
    lifespan=lifespan,
)

mcp-binance-futures