Skip to main content
Glama
Sign In

mcp-optimizer

by dmitryanchikov
GitHub
Python
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

MCP Optimizer

🚀 Mathematical Optimization MCP Server with PuLP and OR-Tools support

🚀 Quick Start

Integration with LLM Clients

Claude Desktop Integration

Option 1: Using uvx (Recommended)

  1. Install Claude Desktop from claude.ai
  2. Open Claude Desktop → Settings → Developer → Edit Config
  3. Add to your claude_desktop_config.json:
{ "mcpServers": { "mcp-optimizer": { "command": "uvx", "args": ["mcp-optimizer"] } } }
  1. Restart Claude Desktop and look for the 🔨 tools icon

Option 2: Using pip

pip install mcp-optimizer

Then add to your Claude Desktop config:

{ "mcpServers": { "mcp-optimizer": { "command": "mcp-optimizer" } } }

Option 3: Using Docker

Method A: Docker with STDIO transport (Recommended for MCP clients)

docker pull ghcr.io/dmitryanchikov/mcp-optimizer:latest

Then add to your Claude Desktop config:

{ "mcpServers": { "mcp-optimizer": { "command": "docker", "args": [ "run", "--rm", "-i", "ghcr.io/dmitryanchikov/mcp-optimizer:latest", "python", "main.py" ] } } }

Method B: Docker with SSE transport (for HTTP/web clients)

# Run SSE server on port 8000 docker run -d -p 8000:8000 ghcr.io/dmitryanchikov/mcp-optimizer:latest \ python -m mcp_optimizer.main --transport sse --host 0.0.0.0 # Or with custom port docker run -d -p 9000:9000 ghcr.io/dmitryanchikov/mcp-optimizer:latest \ python -m mcp_optimizer.main --transport sse --host 0.0.0.0 --port 9000

Then use HTTP client to connect to http://localhost:8000 (requires additional MCP HTTP client setup)

Cursor Integration
  1. Install the MCP extension in Cursor
  2. Add mcp-optimizer to your workspace settings:
{ "mcp.servers": { "mcp-optimizer": { "command": "uvx", "args": ["mcp-optimizer"] } } }
Other LLM Clients

For other MCP-compatible clients (Continue, Cody, etc.), use similar configuration patterns with the appropriate command for your installation method.

Advanced Installation Options

Local Development
# Clone the repository git clone https://github.com/dmitryanchikov/mcp-optimizer.git cd mcp-optimizer # Install dependencies with uv uv sync --extra dev # Run the server uv run python main.py
Local Package Build and Run

For testing and development, you can build the package locally and run it with uvx:

# Build the package locally uv build # Run with uvx from local wheel file uvx --from ./dist/mcp_optimizer-0.3.9-py3-none-any.whl mcp-optimizer # Or run with help to see available options uvx --from ./dist/mcp_optimizer-0.3.9-py3-none-any.whl mcp-optimizer --help # Test the local package with a simple MCP message echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}, "id": 1}' | uvx --from ./dist/mcp_optimizer-0.3.9-py3-none-any.whl mcp-optimizer

Note: The local build creates both wheel (.whl) and source distribution (.tar.gz) files in the dist/ directory. The wheel file is recommended for uvx installation as it's faster and doesn't require compilation.

Troubleshooting: If you encounter event loop issues when using uvx, the package includes automatic detection and handling of existing event loops using nest-asyncio.

Docker with Custom Configuration
# Build locally with optimization git clone https://github.com/dmitryanchikov/mcp-optimizer.git cd mcp-optimizer docker build -t mcp-optimizer:optimized . docker run -p 8000:8000 mcp-optimizer:optimized # Check optimized image size (398MB vs 1.03GB original - 61% reduction!) docker images mcp-optimizer:optimized # Test the optimized image ./scripts/test_docker_optimization.sh
Standalone Server Commands
# Run directly with uvx (no installation needed) uvx mcp-optimizer # Or run specific commands uvx mcp-optimizer --help # With pip installation mcp-optimizer # Or run with Python module (use main.py for stdio mode) python main.py
Transport Modes

MCP Optimizer supports two transport protocols:

  • STDIO: Standard input/output for direct MCP client integration (Claude Desktop, Cursor, etc.)
  • SSE: Server-Sent Events over HTTP for web-based clients and custom integrations

STDIO Transport (Default - for MCP clients like Claude Desktop)

# Default STDIO mode for MCP protocol uvx mcp-optimizer # or uvx mcp-optimizer --transport stdio # or uv run python -m mcp_optimizer.main --transport stdio # or python main.py

SSE Transport (for HTTP/web clients)

# SSE mode for HTTP clients (default port 8000) uvx mcp-optimizer --transport sse # or uv run python -m mcp_optimizer.main --transport sse # Custom host and port uvx mcp-optimizer --transport sse --host 0.0.0.0 --port 9000 # or uv run python -m mcp_optimizer.main --transport sse --host 0.0.0.0 --port 9000 # With debug mode uvx mcp-optimizer --transport sse --debug --log-level DEBUG

Available CLI Options

# Show all available options uvx mcp-optimizer --help # Options: # --transport {stdio,sse} MCP transport protocol (default: stdio) # --port PORT Port for SSE transport (default: 8000) # --host HOST Host for SSE transport (default: 127.0.0.1) # --debug Enable debug mode # --reload Enable auto-reload for development # --log-level {DEBUG,INFO,WARNING,ERROR} Logging level (default: INFO)

🎯 Features

Supported Optimization Problem Types:

  • Linear Programming - Maximize/minimize linear objective functions
  • Assignment Problems - Optimal resource allocation using Hungarian algorithm
  • Transportation Problems - Logistics and supply chain optimization
  • Knapsack Problems - Optimal item selection (0-1, bounded, unbounded)
  • Routing Problems - TSP and VRP with time windows
  • Scheduling Problems - Job and shift scheduling
  • Integer Programming - Discrete optimization problems
  • Financial Optimization - Portfolio optimization and risk management
  • Production Planning - Multi-period production planning

Testing

# Run simple functionality tests uv run python tests/test_integration/comprehensive_test.py # Run comprehensive integration tests uv run python tests/test_integration/comprehensive_test.py # Run all unit tests uv run pytest tests/ -v # Run with coverage uv run pytest tests/ --cov=src/mcp_optimizer --cov-report=html

📊 Usage Examples

Linear Programming

from mcp_optimizer.tools.linear_programming import solve_linear_program # Maximize 3x + 2y subject to: # x + y <= 4 # 2x + y <= 6 # x, y >= 0 objective = {"sense": "maximize", "coefficients": {"x": 3, "y": 2}} variables = { "x": {"type": "continuous", "lower": 0}, "y": {"type": "continuous", "lower": 0} } constraints = [ {"expression": {"x": 1, "y": 1}, "operator": "<=", "rhs": 4}, {"expression": {"x": 2, "y": 1}, "operator": "<=", "rhs": 6} ] result = solve_linear_program(objective, variables, constraints) # Result: x=2.0, y=2.0, objective=10.0

Assignment Problem

from mcp_optimizer.tools.assignment import solve_assignment_problem workers = ["Alice", "Bob", "Charlie"] tasks = ["Task1", "Task2", "Task3"] costs = [ [4, 1, 3], # Alice's costs for each task [2, 0, 5], # Bob's costs for each task [3, 2, 2] # Charlie's costs for each task ] result = solve_assignment_problem(workers, tasks, costs) # Result: Total cost = 5.0 with optimal assignments

Knapsack Problem

from mcp_optimizer.tools.knapsack import solve_knapsack_problem items = [ {"name": "Item1", "weight": 10, "value": 60}, {"name": "Item2", "weight": 20, "value": 100}, {"name": "Item3", "weight": 30, "value": 120} ] result = solve_knapsack_problem(items, capacity=50) # Result: Total value = 220.0 with optimal item selection

Portfolio Optimization

from mcp_optimizer.tools.financial import optimize_portfolio assets = [ {"name": "Stock A", "expected_return": 0.12, "risk": 0.18}, {"name": "Stock B", "expected_return": 0.10, "risk": 0.15}, {"name": "Bond C", "expected_return": 0.06, "risk": 0.08} ] result = optimize_portfolio( assets=assets, objective="minimize_risk", budget=10000, risk_tolerance=0.15 ) # Result: Optimal portfolio allocation with minimized risk

🏗️ Architecture

mcp-optimizer/ ├── src/mcp_optimizer/ │ ├── tools/ # 9 categories of optimization tools │ │ ├── linear_programming.py │ │ ├── assignment.py │ │ ├── knapsack.py │ │ ├── routing.py │ │ ├── scheduling.py │ │ ├── financial.py │ │ └── production.py │ ├── solvers/ # PuLP and OR-Tools integration │ │ ├── pulp_solver.py │ │ └── ortools_solver.py │ ├── schemas/ # Pydantic validation schemas │ ├── utils/ # Utility functions │ ├── config.py # Configuration │ └── mcp_server.py # Main MCP server ├── tests/ # Comprehensive test suite ├── docs/ # Documentation ├── k8s/ # Kubernetes deployment ├── monitoring/ # Grafana/Prometheus setup └── main.py # Entry point

🧪 Test Results

✅ Comprehensive Test Suite

🧪 Starting Comprehensive MCP Optimizer Tests ================================================== ✅ Server Health PASSED ✅ Linear Programming PASSED ✅ Assignment Problems PASSED ✅ Knapsack Problems PASSED ✅ Routing Problems PASSED ✅ Scheduling Problems PASSED ✅ Financial Optimization PASSED ✅ Production Planning PASSED ✅ Performance Test PASSED 📊 Test Results: 9 passed, 0 failed 🎉 All tests passed! MCP Optimizer is ready for production!

✅ Unit Tests

  • 66 tests passed, 9 skipped
  • Execution time: 0.45 seconds
  • All core components functional

📈 Performance Metrics

  • Linear Programming: ~0.01s
  • Assignment Problems: ~0.01s
  • Knapsack Problems: ~0.01s
  • Complex test suite: 0.02s for 3 optimization problems
  • Overall performance: 🚀 Excellent!

🔧 Technical Details

Core Solvers

  • OR-Tools: For assignment, transportation, knapsack problems
  • PuLP: For linear/integer programming
  • FastMCP: For MCP server integration

Supported Solvers

  • CBC, GLPK, GUROBI, CPLEX (via PuLP)
  • SCIP, CP-SAT (via OR-Tools)

Key Features

  • ✅ Full MCP protocol integration
  • ✅ Comprehensive input validation
  • ✅ Robust error handling
  • ✅ High-performance optimization
  • ✅ Production-ready architecture
  • ✅ Extensive test coverage
  • ✅ Docker and Kubernetes support

📋 Requirements

  • Python 3.11+
  • uv (for dependency management)
  • OR-Tools (automatically installed)
  • PuLP (automatically installed)

🚀 Production Deployment

Docker

# Build image docker build -t mcp-optimizer . # Run container docker run -p 8000:8000 mcp-optimizer

Kubernetes

# Deploy to Kubernetes kubectl apply -f k8s/

Monitoring

# Start monitoring stack docker-compose up -d

🎯 Project Status

✅ PRODUCTION READY 🚀

  • All core optimization tools implemented and tested
  • MCP server fully functional
  • Comprehensive test coverage (66 unit tests + 9 integration tests)
  • OR-Tools integration confirmed working
  • Performance optimized (< 30s for complex test suites)
  • Ready for production deployment

📖 Usage Examples

The examples/ directory contains practical examples and prompts for using MCP Optimizer with Large Language Models (LLMs):

Available Examples

  • 📊 Linear Programming (RU | EN)
    • Production optimization, diet planning, transportation, blending problems
  • 👥 Assignment Problems (RU | EN)
    • Employee-project assignment, machine-order allocation, task distribution
  • 💰 Portfolio Optimization (RU | EN)
    • Investment portfolios, retirement planning, risk management

How to Use Examples

  1. For LLM Integration: Copy the prompt text and provide it to your LLM with MCP Optimizer access
  2. For Direct API Usage: Use the provided API structures directly with MCP Optimizer functions
  3. For Learning: Understand different optimization problem types and formulations

Each example includes:

  • Problem descriptions and real-world scenarios
  • Ready-to-use prompts for LLMs
  • Technical API structures
  • Common activation phrases
  • Practical applications

🔄 Recent Updates

Latest Release Features:

  1. Function Exports - Added exportable functions to all tool modules:
    • solve_linear_program() in linear_programming.py
    • solve_assignment_problem() in assignment.py
    • solve_knapsack_problem() in knapsack.py
    • optimize_portfolio() in financial.py
    • optimize_production() in production.py
  2. Enhanced Testing - Updated comprehensive test suite with correct function signatures
  3. OR-Tools Integration - Confirmed full functionality of all OR-Tools components

🚀 Fully Automated Release Process

New Simplified Git Flow (3 steps!)

The project uses a fully automated release process:

1. Create Release Branch
# For minor release (auto-increment) uv run python scripts/release.py --type minor # For specific version uv run python scripts/release.py 0.2.0 # For hotfix uv run python scripts/release.py --hotfix --type patch # Preview changes uv run python scripts/release.py --type minor --dry-run
2. Create PR to main
# Create PR: release/v0.3.0 → main gh pr create --base main --head release/v0.3.0 --title "Release v0.3.0"
3. Merge PR - DONE! 🎉

After PR merge, automatically happens:

  • ✅ Create tag v0.3.0
  • ✅ Publish to PyPI
  • ✅ Publish Docker images
  • ✅ Create GitHub Release
  • ✅ Merge main back to develop
  • ✅ Cleanup release branch

NO NEED to run finalize_release.py manually anymore!

🔒 Secure Detection: Uses hybrid approach combining GitHub branch protection with automated release detection. See Release Process for details.

Automated Release Pipeline

The CI/CD pipeline automatically handles:

  • ✅ Release Candidates: Built from release/* branches
  • ✅ Production Releases: Triggered by version tags on main
  • ✅ PyPI Publishing: Automatic on tag creation
  • ✅ Docker Images: Multi-architecture builds
  • ✅ GitHub Releases: With artifacts and release notes

CI/CD Pipeline

The GitHub Actions workflow automatically:

  • ✅ Runs tests on Python 3.11 and 3.12
  • ✅ Performs security scanning
  • ✅ Builds and pushes Docker images
  • ✅ Publishes to PyPI on tag creation
  • ✅ Creates GitHub releases

Requirements for PyPI Publication

  • Set PYPI_API_TOKEN secret in GitHub repository
  • Ensure all tests pass
  • Follow semantic versioning

🛠️ Development Tools

Debug Tools

Use the debug script to inspect MCP server structure:

# Run debug tools to check server structure uv run python scripts/debug_tools.py # This will show: # - Available MCP tools # - Tool types and attributes # - Server configuration

Comprehensive Testing

Run the full integration test suite:

# Run comprehensive tests uv run python tests/test_integration/comprehensive_test.py # This tests: # - All optimization tools (9 categories) # - Server health and functionality # - Performance benchmarks # - End-to-end workflows

Docker Build Instructions

Image Details
  • Base: Python 3.12 Slim (Debian-based)
  • Size: ~649MB (optimized with multi-stage builds)
  • Architecture: Multi-platform support (x86_64, ARM64)
  • Security: Non-root user, minimal dependencies
  • Performance: Optimized Python bytecode, cleaned build artifacts
Local Build Commands
# Standard build docker build -t mcp-optimizer:latest . # Build with development dependencies docker build --build-arg ENV=development -t mcp-optimizer:dev . # Build with cache mount for faster rebuilds docker build --mount=type=cache,target=/build/.uv -t mcp-optimizer . # Check image size docker images mcp-optimizer # Run container docker run -p 8000:8000 mcp-optimizer:latest # For development with volume mounting docker run -p 8000:8000 -v $(pwd):/app mcp-optimizer:latest # Test container functionality docker run --rm mcp-optimizer:latest python -c "from mcp_optimizer.mcp_server import create_mcp_server; print('✅ MCP Optimizer works!')"

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Git Flow Policy

This project follows a standard Git Flow workflow:

  • Feature branches → develop branch
  • Release branches → main branch
  • Hotfix branches → main and develop branches

📚 Documentation:

Development Setup

# Clone and setup git clone https://github.com/dmitryanchikov/mcp-optimizer.git cd mcp-optimizer # Create feature branch from develop git checkout develop git checkout -b feature/your-feature-name # Install dependencies uv sync --extra dev # Run tests uv run pytest tests/ -v # Run linting uv run ruff check src/ uv run mypy src/ # Create PR to develop branch (not main!)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • OR-Tools - Google's optimization tools
  • PuLP - Linear programming in Python
  • FastMCP - Fast MCP server implementation

📞 Support

Made with ❤️ for the optimization community

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

mcp-optimizer

  1. 🚀 Quick Start
    1. Integration with LLM Clients
    2. Advanced Installation Options
  2. 🎯 Features
    1. Supported Optimization Problem Types:
    2. Testing
  3. 📊 Usage Examples
    1. Linear Programming
    2. Assignment Problem
    3. Knapsack Problem
    4. Portfolio Optimization
  4. 🏗️ Architecture
    1. 🧪 Test Results
      1. ✅ Comprehensive Test Suite
      2. ✅ Unit Tests
      3. 📈 Performance Metrics
    2. 🔧 Technical Details
      1. Core Solvers
      2. Supported Solvers
      3. Key Features
    3. 📋 Requirements
      1. 🚀 Production Deployment
        1. Docker
        2. Kubernetes
        3. Monitoring
      2. 🎯 Project Status
        1. 📖 Usage Examples
          1. Available Examples
          2. How to Use Examples
        2. 🔄 Recent Updates
          1. Latest Release Features:
        3. 🚀 Fully Automated Release Process
          1. New Simplified Git Flow (3 steps!)
          2. Automated Release Pipeline
          3. CI/CD Pipeline
          4. Requirements for PyPI Publication
        4. 🛠️ Development Tools
          1. Debug Tools
          2. Comprehensive Testing
          3. Docker Build Instructions
        5. 🤝 Contributing
          1. Git Flow Policy
          2. Development Setup
        6. 📄 License
          1. 🙏 Acknowledgments
            1. 📞 Support

              Related MCP Servers

              View all related MCP servers

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/dmitryanchikov/mcp-optimizer'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server