trading-position-risk-mcp

Not financial advice. Use at your own risk. This is a guardrail that enforces rules you configure. It cannot see your broker, does not place orders, and trusts what the agent reports. It can be wrong, and trading can lose money. Test with paper trading first. See Security and trust model.

A deterministic position-sizing and pre-trade risk server for trading agents, served over MCP.

Agents never do sizing math themselves. They ask this server. It applies a rulebook that the human owns, and it answers APPROVED / RESIZED / REJECTED with the rules that fired and an approval token.

The core formula reproduces the E-Mini (ES) Position Sizing Calculator v4.5 spreadsheet exactly (floor(equity × risk% ÷ (stop points × point value))). On top of that it adds costs, micro fallback, portfolio heat, exposure buckets, a daily-loss lockout, drawdown tiers and options.

Quick start

pip install -e ".[dev]"
pytest                                   # 190+ tests, including spreadsheet parity
position-risk-mcp                        # stdio MCP server
position-risk-mcp --http 8765            # streamable HTTP instead (loopback only; see Security)
position-risk-admin size ES long 6500 6498 --no-costs    # same answer as the sheet: 5 contracts

Claude Desktop / Claude Code config:

{
  "mcpServers": {
    "position-risk": {
      "command": "position-risk-mcp",
      "env": {
        "POSITION_RISK_RULES": "/path/to/config/rules.yaml",
        "POSITION_RISK_STATE": "~/.position-risk-mcp/risk_state.json"
      }
    }
  }
}

Order flow the agent must follow

check_trade ──► place order (≤ approved_contracts, before expiry) ──► record_fill ──► update_stop* ──► record_close

By design, no tool can change equity, rules or lockouts. Those are owner-only, through the admin CLI:

position-risk-admin show
position-risk-admin set-equity 61250 --note "synced with broker"
position-risk-admin reset-peak --note "reviewed drawdown, resuming"
position-risk-admin unlock-day --note "..."
position-risk-admin remove-position pos_ab12cd34ef --note "closed manually"

What check_trade enforces (config/rules.yaml)

Order of evaluation: lockout → drawdown halt → position count → order validity → min(per-trade, heat, bucket, daily budget, margin, cap). The smallest limit wins and is reported in binding_limits.

Examples (with the default $55,000 account)

Security and trust model

• Pending approvals reserve risk. Until filled, cancelled or expired, an approval counts against heat, bucket, daily-budget, margin and position-count limits. A new check_trade for a symbol replaces that symbol's earlier pending approval.
• The agent reports its own fills and closes. The server cannot see your broker. An agent that skips record_close or reports a false exit_price makes equity, lockouts and drawdown tiers wrong. Treat the server as a guardrail for a cooperative agent, not as enforcement, and reconcile with your broker using position-risk-admin set-equity / remove-position.
• HTTP transport. It binds to loopback by default. Any other --host is refused unless POSITION_RISK_TOKEN (24+ characters) is set; clients then send Authorization: Bearer <token>. There is no TLS: put a reverse proxy in front for anything beyond localhost. Every tool is available to any authenticated client.
• Rulebook edits. State remembers which rulebook fingerprint created it. If rules.yaml changes, rulebook_changed is true in every response until the owner runs position-risk-admin ack-rulebook.

Design notes

• Decimal math throughout, so floor() never turns 11.0 into 10.999.
• Equity is never an input. It starts at account.starting_equity, moves with realized P&L and can be synced with set-equity. A hallucinated account size can't inflate a position.
• Every response carries the rulebook version and fingerprint, and every state change is journaled, so you can audit which rules approved which trade.
• The state store is pluggable. JsonFileStore (file lock + atomic write) is the default. For AWS, implement the same transaction() / read() interface on DynamoDB with a conditional version write, and run the server behind Lambda/Fargate with --http.
• Margins in instruments.yaml are null on purpose. They change, and they differ by broker and session, so set them from your broker.

Roadmap ideas

• Broker adapters (equity and positions pulled from the broker instead of tracked locally)
• DynamoDB store + Lambda handler
• Futures options; per-symbol session calendars for the day rollover
• Volatility-regime multiplier (e.g. from a VIX regime feed)

License

MIT.

This software enforces rules you configure. It is not financial advice.