scenario.com-mcp-server
If you are the rightful owner of scenario.com-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Scenario.com MCP Server allows for image generation and background removal using the Scenario.com API.
Scenario.com MCP Server
This project provides a Model Context Protocol (MCP) server for the Scenario.com API. The server allows you to generate images from text prompts and remove backgrounds from images using the Scenario.com platform (https://app.scenario.com/).
Repository Structure
The repository is organized as follows:
-
src/: Core source code and configuration files
server.py
: Main MCP server implementationrequirements.txt
: Project dependenciessetup.py
: Installation script.gitignore
: Git ignore rulesremove_bg_command.txt
: Command reference for background removal
-
examples/: Example scripts demonstrating API usage
client_example.py
: Main example clientGet the details of an asset.py
: Example of retrieving asset detailsTrigger a new image generation in Txt2Img mode.py
: Example of generating imagesErase background from image.py
: Example of background removalGet job data by job ID.py
: Example of checking job statusdownload_image.py
: Example of downloading generated images
-
scripts/: Utility scripts for running the server and examples
start_server.bat
/start_server.sh
: Scripts to start the MCP server using themcp dev
commandrun_client_example.bat
/run_client_example.sh
: Scripts to run the example client that demonstrates how to use the MCP serverrun_tests.bat
/run_tests.sh
: Scripts to run the test suite that verifies the MCP server functionality
-
tests/: Test files
test_server.py
: Tests and documentation for the MCP server
-
assets/: Sample images and resources
warrior_no_background.png
: Sample image with background removedwarrior_with_background.jpg
: Sample original image
-
docs/: Documentation
README.md
: Project documentationDESIGN_PLAN.md
: Design documentation
-
scenario-ai/: Virtual environment for the project
Setup
-
Clone this repository
-
(Recommended) Set up a virtual environment:
# Using venv python -m venv scenario-ai .\scenario-ai\Scripts\activate # Windows source scenario-ai/bin/activate # Linux/macOS # Or using conda conda create -n scenario-ai python=3.8 conda activate scenario-ai
-
Install the required dependencies (either method works):
# Method 1: Using requirements.txt pip install -r src/requirements.txt # Method 2: Using setup.py (installs as package) pip install -e .
-
Create a
.env
file in the root directory with your Scenario.com API credentials:SCENARIO_API_KEY=your_api_key SCENARIO_API_SECRET=your_api_secret SCENARIO_MODEL_ID=model_KMeeJU9mpcfHKB7a1hv9vyW9 # Change to preferred model
Important: The server loads environment variables directly from this
.env
file, so make sure it's properly configured. -
Install the MCP SDK and python-dotenv:
pip install mcp
-
Add this MCP server configuration to your Cline/Roo-Cline/Cursor/VS Code settings:
"scenario-ai": { "command": "python", "args": [ "path/to/your/local/scenario.com-mcp-server/src/server.py" ], "disabled": false, "autoApprove": [], "alwaysAllow": [] }
Note: Environment variables are loaded from the
.env
file, so they don't need to be specified in the MCP server configuration.
Running the Server
To run the server:
# Standard method
python src/server.py
# Recommended: Using MCP dev mode (starts inspector)
mcp dev src/server.py
# Or use the provided scripts:
# Windows
scripts/start_server.bat
# Linux/macOS
./scripts/start_server.sh
When running with mcp dev
, you'll see output like:
Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀
New SSE connection
Available MCP Tools
The Scenario.com MCP Server provides the following tools that can be used with the Roo-Cline interface:
Tools
-
generate_image: Generate an image from a text prompt
- Parameters:
prompt
(required): The text prompt describing the image to generatemodel_id
(optional): The model ID to use (defaults to environment variable)negative_prompt
(optional): Text describing what to avoid in the imagenum_samples
(optional): Number of images to generate
- Parameters:
-
remove_background: Remove the background from an image
- Parameters:
asset_id
(required): The asset ID of the image to process
- Parameters:
Resources
- status://info: Get information about the server status
- job://{job_id}: Get information about a job
- asset://{asset_id}: Get information about an asset
Using the Examples
See the examples/client_example.py
file for an example of how to use the server.
To run the example client:
# Windows
scripts/run_client_example.bat
# Linux/macOS
./scripts/run_client_example.sh
Scripts
The scripts/
directory contains utility scripts to help you run the server, examples, and tests:
Server Scripts
-
start_server.bat
(Windows) /start_server.sh
(Linux/macOS): These scripts start the MCP server using themcp dev
command, which runs the server in development mode.Usage:
# Windows scripts/start_server.bat # Linux/macOS ./scripts/start_server.sh
Example Scripts
-
run_client_example.bat
(Windows) /run_client_example.sh
(Linux/macOS): These scripts run the example client that demonstrates how to use the MCP server.Usage:
# Windows scripts/run_client_example.bat # Linux/macOS ./scripts/run_client_example.sh
Test Scripts
-
run_tests.bat
(Windows) /run_tests.sh
(Linux/macOS): These scripts run the test suite that verifies the MCP server functionality.Usage:
# Windows scripts/run_tests.bat # Linux/macOS ./scripts/run_tests.sh
Running Tests and Viewing Documentation
To run the tests and view the documentation:
# Windows
scripts/run_tests.bat
# Linux/macOS
./scripts/run_tests.sh
The test_server.py
file provides comprehensive documentation on how to use the Scenario.com MCP Server, including:
- Server setup instructions
- Available tools and their parameters
- Available resources
- Example usage with the Roo-Cline interface
- A complete workflow for generating images and removing backgrounds
Running the tests will display this documentation, which serves as a guide for using the MCP server.
Troubleshooting
Server Won't Start
If you encounter issues starting the server, check the following:
-
Make sure the MCP SDK and python-dotenv are installed:
pip install mcp python-dotenv
-
Check that your Python environment has all the required dependencies:
pip install -r src/requirements.txt
-
Verify that your
.env
file in the root directory is properly configured with your Scenario.com API credentials:SCENARIO_API_KEY=your_api_key SCENARIO_API_SECRET=your_api_secret SCENARIO_MODEL_ID=your_model_id
-
If you're using a virtual environment, make sure it's activated before running the server.
API Errors
If you encounter errors when using the API:
- Check that your API credentials are correct.
- Verify that the model ID you're using is valid.
- Check the Scenario.com API documentation for any service disruptions or changes.
License
This project is licensed under the MIT License - see the LICENSE file for details.