USolver is a Model Context Protocol server that provides tools for solving various optimization problems including combinatorial, convex, integer programming, and non-linear optimization challenges. It integrates with solvers like highs, ortools, cvxpy, and z3 to handle different types of optimization problems, and can be used with Claude Desktop or Cursor.
To install the USolver MCP server, run the installation script using the uv package manager:
uv run install.py
This will install the MCP server for Claude Desktop and/or Cursor. After installation, open Claude or Cursor and you should see the usolver tool available in the tool list.
Alternatively, you can run the MCP server directly from the GitHub Container Registry:
docker run -p 8081:8081 ghcr.io/sdiehl/usolver:latest
To configure your client, add the following JSON configuration:
{
"mcpServers": {
"sympy-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"-p",
"8081:8081",
"--rm",
"ghcr.io/sdiehl/usolver:latest"
]
}
}
}
USolver can solve a wide range of optimization problems across different domains. Here are some examples of how to use it:
You can solve complex logic puzzles by describing them to USolver. For example, this coin problem:
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 cant 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?
USolver will convert this into a constraint system and solve it with Z3, returning:
Your friend has: 1 half dollar, 1 quarter, and 4 dimes
This totals 50¢ + 25¢ + 40¢ = 115¢ = $1.15 ✓
This is exactly 6 coins ✓
For financial applications, you can use USolver to solve portfolio optimization problems:
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%
USolver will provide an optimal allocation:
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
For engineering applications, you can solve problems like this pipeline design:
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
You can solve linear programming problems:
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]
The optimal solution will be:
x = 15.0
y = 1.25
Objective value = 205.0
For convex optimization:
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]
For scheduling problems:
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.
For more complex problems requiring multiple optimization methods:
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)
To add this MCP server to Claude Code, run this command in your terminal:
claude mcp add-json "usolver" '{"command":"docker","args":["run","-i","-p","8081:8081","--rm","ghcr.io/sdiehl/usolver:latest"]}'See the official Claude Code MCP documentation for more details.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.
To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".
When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:
{
"mcpServers": {
"usolver": {
"command": "docker",
"args": [
"run",
"-i",
"-p",
"8081:8081",
"--rm",
"ghcr.io/sdiehl/usolver:latest"
]
}
}
}To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json2. Add this to your configuration file:
{
"mcpServers": {
"usolver": {
"command": "docker",
"args": [
"run",
"-i",
"-p",
"8081:8081",
"--rm",
"ghcr.io/sdiehl/usolver:latest"
]
}
}
}3. Restart Claude Desktop for the changes to take effect