Usolver

🚀 USolver

USolver is a Model Context Protocol server that provides tools for solving combinatorial, convex, integer programming, and non - linear optimization problems. It offers interfaces to the following solvers:

• highs - A solver for linear and mixed - integer programming.
• ortools - A solver for combinatorial optimization.
• cvxpy - A solver for convex optimization.
• z3 - An SMT solver for booleans, integers, reals, and strings.

🚀 Quick Start

To install, run the install.py script. This will install the MPC server for Claude Desktop and/or Cursor.

uv run install.py

Then open Claude or Cursor, and you should see the MCP tool usolver in the tool list.

✨ Features

• Exposes interfaces to multiple solvers for different types of optimization problems.
• Provides a variety of example use - cases for different application scenarios.

📦 Installation

Run the following command to install:

uv run install.py

💻 Usage Examples

Basic Usage

To run individual solver examples, you can invoke the individual example modules. Each module contains a docstring that can be used to prompt the language model to solve the problem.

Examples List

• Chemical Engineering - Optimize pipeline design for fluid transport systems using the Z3 SMT solver, considering flow continuity, pressure drop, and economic constraints.
• Chained Solvers - Optimize a multi - stage restaurant problem by combining OR - Tools for table layout and CVXPY for staff scheduling.
• Job Shop Scheduling - Solve a complex scheduling problem using OR - Tools to minimize makespan while respecting operation precedence and machine capacity.
• Logistics - Optimize a transportation network using HiGHS to minimize shipping costs in multi - stage supply chains.
• Nurse Scheduling - Schedule hospital staff using OR - Tools to assign nurses to shifts with fairness and availability constraints.
• Portfolio Theory - Optimize a modern portfolio using CVXPY to maximize returns while constraining risk across asset classes.
• Production Planning - Optimize manufacturing using HiGHS to maximize profit subject to machine, labor, and material constraints.
• Resource Allocation - Select a project portfolio using HiGHS mixed - integer programming to maximize value within budget and resource limits.
• Network Flow - Optimize the shortest path using HiGHS linear programming to find minimum - cost routes through directed graphs with flow conservation constraints.
• Coin Problem - Solve a classic logic puzzle using Z3 to find which 6 US coins total $1.15 but cannot make change for various denominations.
• Cryptarithmetic - Solve cryptarithmetic puzzles like SEND + MORE = MONEY using Z3 constraint programming.
• Knapsack Problem - Solve the classic 0/1 knapsack optimization problem using OR - Tools to maximize value within weight constraints.
• Multilinear Optimization - Solve a linear programming problem with mixed constraints using Z3 to minimize objective functions subject to linear inequalities.
• N - Queens - Place N queens on an N×N chessboard using OR - Tools constraint programming with no attacking positions.
• Sparse Solver - Demonstrate large - scale optimization using sparse matrix formats for memory - efficient resource allocation across facilities and time periods.

Advanced Usage

Logic Puzzle

You and a friend pass by a standard coin - operated vending machine and you decide to get a candy bar.
The price is US $0.95, but after checking your pockets you only have a dollar (US $1) and the machine
only takes coins. You turn to your friend and have this conversation:

You: Hey, do you have change for a dollar?
Friend: Let's see. I have 6 US coins but, although they add up to a US $1.15, I can't break a dollar.
You: Huh? Can you make change for half a dollar?
Friend: No.
You: How about a quarter?
Friend: Nope, and before you ask I can't make change for a dime or nickel either.
You: Really? and these six coins are all US government coins currently in production?
Friend: Yes.
You: Well can you just put your coins into the vending machine and buy me a candy bar, and I'll pay you back?
Friend: Sorry, I would like to but I can't with the coins I have.

What coins are your friend holding?

This can be fed into usolver, and it will generate a constraint system: $C$ is the collection of the six unknown coin values, $c_1$ through $c_6$, each of which must be a positive whole number representing cents. $$ C = {c_1, c_2, c_3, c_4, c_5, c_6}, \quad \text{where each } c_i \in \mathbb{Z}^+ $$ $\mathcal{S}$ is the collection of every possible way you could choose two or more of your six coins. $$ \mathcal{S} = {S \mid S \subseteq C \land |S| \geq 2 } $$ Exclude the 50 - cent coin from being used in the vending machine. $$ v(x) = \begin{cases} 0 & \text{if } x = 50 \ x & \text{if } x \neq 50 \end{cases} $$ Constraint 0: The sum of the values of all six coins is 115 cents. $$ \sum_{i = 1}^{6} c_i = 115 $$ Constraint 1: Cannot make change for a dollar. $$ \forall S \in \mathcal{S}, \quad \sum_{x \in S} x \neq 100 $$ Constraint 2: Cannot make change for half a dollar. $$ \forall S \in \mathcal{S}, \quad \sum_{x \in S} x \neq 50 $$ Constraint 3: Cannot make change for a quarter. $$ \forall S \in \mathcal{S}, \quad \sum_{x \in S} x \neq 25 $$ Constraint 4: Cannot make change for a dime. $$ \forall S \in \mathcal{S}, \quad \sum_{x \in S} x \neq 10 $$ Constraint 5: Cannot make change for a nickel. $$ \forall S \in \mathcal{S}, \quad \sum_{x \in S} x \neq 5 $$ Constraint 6: Cannot buy the candy bar for 95 cents if the half - dollar is excluded. $$ \forall S \in \mathcal{S}, \quad \sum_{x \in S} v(x) \neq 95 $$ If you feed this to the solver, it will synthesize the above constraint system, solve it with Z3, and return the solution.

Your friend has: 1 half - dollar, 1 quarter, and 4 dimes
This totals 50¢ + 25¢ + 40¢ = 115¢ = $1.15 ✓
This is exactly 6 coins ✓

Modern Portfolio Theory

A finance example:

Objective: Maximize expected portfolio return
Constraints:

Bonds allocation cannot exceed 40%
Stocks allocation cannot exceed 60%
Real Estate allocation cannot exceed 30%
Commodities allocation cannot exceed 20%
All allocations must be non - negative
Total allocation must equal exactly 100%
Total weighted portfolio risk cannot exceed 10%

Given Data:

Expected returns: Bonds 8%, Stocks 12%, Real Estate 10%, Commodities 15%
Risk factors: Bonds 2%, Stocks 15%, Real Estate 8%, Commodities 20%

This is compiled by the language model into a convex optimization problem that can be solved by cvxopt. $$ \begin{align} \text{maximize} \quad & 0.08x_1 + 0.12x_2 + 0.10x_3 + 0.15x_4 \ \text{subject to} \quad & x_1 + x_2 + x_3 + x_4 = 1 \ & x_1 \leq 0.4 \ & x_2 \leq 0.6 \ & x_3 \leq 0.3 \ & x_4 \leq 0.2 \ & 0.02x_1 + 0.15x_2 + 0.08x_3 + 0.20x_4 \leq 0.10 \ & x_1, x_2, x_3, x_4 \geq 0 \end{align} $$ Where:

• $x_1$ = Bonds allocation
• $x_2$ = Stocks allocation
• $x_3$ = Real Estate allocation
• $x_4$ = Commodities allocation

The answer is then:

Bonds: 30.0%
Stocks: 20.0%
Real Estate: 30.0% (at maximum allowed)
Commodities: 20.0% (at maximum allowed)
Maximum Expected Return: 10.8% annually

Z3

A chemical engineering example:

Use usolver to design a water transport pipeline with the following requirements:

* Volumetric flow rate: 0.05 m³/s
* Pipe length: 100 m
* Water density: 1000 kg/m³
* Maximum allowable pressure drop: 50 kPa
* Flow continuity: Q = π(D/2)² × v
* Pressure drop: ΔP = f(L/D)(ρv²/2), where f ≈ 0.02 for turbulent flow
* Practical limits: 0.05 ≤ D ≤ 0.5 m, 0.5 ≤ v ≤ 8 m/s
* Pressure constraint: ΔP ≤ 50,000 Pa
* Find: optimal pipe diameter and flow velocity

Linear Programming

A multilinear optimization example:

Use usolver to solve the following linear programming problem:

Minimize: 12x + 20y
Subject to: 6x + 8y ≥ 100
           7x + 12y ≥ 120
           x ≥ 0
           y ∈ [0, 3]

This is compiled by the language model into a constraint satisfaction problem that can be solved with Z3. $$ \begin{aligned} \text{minimize} \quad & 12x + 20y \ \text{subject to} \quad & 6x + 8y \geq 100 \ & 7x + 12y \geq 120 \ & x \geq 0 \ & y \in [0, 3] \end{aligned} $$ Where:

• $x$ = First decision variable (continuous, non - negative)
• $y$ = Second decision variable (continuous, bounded)

The optimal solution is:

x = 15.0
y = 1.25
Objective value = 205.0

CVXPY

A simple convex optimization problem minimizing the 2 - norm of a linear system:

Use usolver to solve the following convex optimization problem:

Minimize: ||Ax - b||₂²
Subject to: 0 ≤ x ≤ 1
where 
  A = [1.0, - 0.5; 0.5, 2.0; 0.0, 1.0] 
  b = [2.0, 1.0, - 1.0]

OR - Tools

A classic worker shift scheduling problem:

Use usolver to solve a nurse scheduling problem with the following requirements:

* Schedule 4 nurses (Alice, Bob, Charlie, Diana) across 3 shifts over (Monday, Tuesday, Wednesday)
* Shifts: Morning (7AM - 3PM), Evening (3PM - 11PM), Night (11PM - 7AM)
* Each shift must be assigned to exactly one nurse each day
* Each nurse works at most one shift per day
* Distribute shifts evenly (2 - 3 shifts per nurse over the period)
* Charlie can't work on Tuesday.

Chained Examples

A chained example that uses both OR - Tools to optimize for table layout and CVXPY to optimize for staff scheduling.

Use usolver to optimize a restaurant's layout and staffing with the following requirements in two parts. Use combinatorial optimization to optimize for table layout and convex optimization to optimize for staff scheduling.

* Part 1: Optimize table layout
  - Mix of 2 - seater, 4 - seater, and 6 - seater tables
  - Maximum floor space: 150 m²
  - Space requirements: 4m² (2 - seater), 6m² (4 - seater), 9m² (6 - seater)
  - Maximum 20 tables total
  - Minimum mix: 2× 2 - seaters, 3× 4 - seaters, 1× 6 - seater
  - Objective: Maximize total seating capacity

* Part 2: Optimize staff scheduling using Part 1's capacity
  - 12 - hour operating day
  - Each staff member can handle 20 seats
  - Minimum 2 staff per hour
  - Maximum staff change between hours: 2 people
  - Variable demand: 40% - 100% of capacity
  - Objective: Minimize labor cost ($25/hour per staff)

📚 Documentation

The provided examples and their corresponding constraint systems serve as a detailed guide on how to use the usolver for different types of optimization problems.

📦 Docker Usage

You can also run the MCP server directly from the GitHub Container Registry.

docker run -p 8081:8081 ghcr.io/sdiehl/usolver:latest

Then add the following to your client:

{
  "mcpServers": {
    "sympy - mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-p",
        "8081:8081",
        "--rm",
        "ghcr.io/sdiehl/usolver:latest"
      ]
    }
  }
}

📄 License

This project is released under the Apache License 2.0. See the LICENSE file for details.