Content
# Rescale MCP Server
A Model Context Protocol (MCP) server that provides access to Rescale's Platform API through Claude Desktop and other MCP clients.
## Installation & Usage
### Prerequisites
- **Python 3.11+**: Install from [python.org](https://www.python.org/downloads/) or `brew install python@3.11`
- **Git**: Usually pre-installed on macOS/Linux, or install from [git-scm.com](https://git-scm.com)
- **pip**: Comes with Python installation
### Quick Installation
```bash
brew install python@3.11
python3 -m venv venv
source venv/bin/activate
python3 --version # make sure its 3.11+
pip install git+https://github.com/rescale-labs/rescale-mcp-server.git
```
### Claude Desktop Setup
1. Get your API token from: https://platform.rescale.com/user/settings/
2. Find your command path by running: `which rescale-mcp-server` (after activating your environment)
3. Add to Claude Desktop config: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"rescale": {
"command": "REPLACE_WITH_YOUR_PATH_FROM_STEP_2",
"args": [
"--token", "REPLACE_WITH_YOUR_API_TOKEN",
"--base-url", "https://platform.rescale.com/api/v3"
]
}
}
}
```
3. Restart Claude Desktop
4. You'll see Rescale API tools available in Claude!
## Getting Started
Once installed, you can start using Rescale directly in Claude Desktop:
1. **Open Claude Desktop** - The Rescale tools will be automatically available
2. **Try basic commands** - Ask Claude: "List my Rescale jobs" or "Show available hardware types"
3. **Create and submit jobs** - Ask Claude: "Create a new compute job using OpenFOAM"
**Available Features:**
- **Job Management**: Create, submit, monitor, and control compute jobs and workstations
- **File Operations**: Upload, download, and manage files and job results
- **Resource Discovery**: Browse available hardware, software.
- **Detailed Documentation**: For a complete list of available tools and their usage, see the [documentation](./docs/TOOLS.md)
**🎉 That's it! You can now use Rescale directly in Claude Desktop. The examples below are optional for advanced users.**
---
## Advanced Usage Examples (Optional)
*The examples below are for developers who want to integrate the Rescale MCP server programmatically into their own applications. Most users can skip this section.*
The `examples/` directory contains sample integration code showing how to use the Rescale MCP server programmatically:
### HTTP Client Example
```bash
# Start the MCP server in HTTP mode (in one terminal)
python -m src.rescale_api_mcp_server.cli --token YOUR_TOKEN --transport http --port 8000
# Run the HTTP client example (in another terminal)
cd examples/http
python simple_http_client.py
```
The HTTP client uses the FastMCP library for clean, high-level integration with MCP servers.
### STDIO Client Example
```bash
# Run the STDIO client (no separate server needed)
cd examples/stdio
python simple_stdio_client.py
```
The STDIO client demonstrates direct MCP protocol communication via subprocess, showing lower-level integration.
Both examples will list your Rescale jobs and display detailed job information. Make sure you have:
- Your Rescale API token set in the environment variable `RESCALE_API_TOKEN`
- Or modify the examples to include your token directly
---
## For Developers
### Development Setup
```bash
# Clone repository
git clone https://github.com/rescale-labs/rescale-mcp-server.git
cd rescale-mcp
# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate # On macOS/Linux
uv sync
# Test to verify
python tests/quick_test.py
```
### Manual Server Testing
```bash
# Run server directly
python src/rescale_api_mcp_server/server.py --token YOUR_TOKEN --base-url https://platform.rescale.com/api/v3
# HTTP mode for web testing
python src/rescale_api_mcp_server/server.py --token YOUR_TOKEN --base-url https://platform.rescale.com/api/v3 --transport http --port 8000
```
### Running Tests
```bash
# Run only unit tests (no API calls required)
python -m pytest tests/unit/ -v
# Run only integration tests (requires API token)
RESCALE_API_TOKEN="your_token_here" python -m pytest tests/integration/ -v
# Run specific test files
python -m pytest tests/unit/test_tool_filters.py -v
python -m pytest tests/integration/test_job_tools.py -v -s
# Run with custom base URL (optional)
RESCALE_API_TOKEN="your_token_here" RESCALE_BASE_URL="https://custom.rescale.com/api/v3" python -m pytest tests/integration/ -v
```
**Test Requirements:**
- **Unit Tests**: No special requirements - test individual components in isolation
- **Integration Tests**: Require `RESCALE_API_TOKEN` environment variable for real API calls
- **Optional**: Set `RESCALE_BASE_URL` to test against different Rescale environments (defaults to `https://platform.rescale.com/api/v3`)
**Requirements:** Python 3.11+, uv package manager, valid Rescale API token
## License
All code and tools shared at Rescale-Labs are licensed under the MIT [License](./LICENSE).
