csharp-runner

The C# Runner MCP server provides a hosted environment to execute C# code via an MCP interface as well as a traditional HTTP API. The MCP endpoint is exposed at /mcp and currently exposes a run_code tool that accepts a snippet of C# code and returns the execution results. To use MCP, send a JSON-RPC style request targeting the run_code tool with the C# code you want to execute; the server will run the code inside isolated containers and stream results back if using the HTTP path. For convenience, you can also interact via the HTTP API at /api/run for streaming output (stdout, result, and errors) using Server-Sent Events (SSE). The system is designed with a Host-Worker architecture: a Host service provides the public API and coordinates a pool of Worker containers that execute the code in isolation, with support for resource limits, timeouts, and isolation policies. The MCP path is particularly useful for integrating into automation pipelines or external tooling that relies on JSON-RPC calls.

Prerequisites:

• Docker and Docker Compose installed on the host machine
• Optional: .NET SDK if you choose to run the Host/Worker locally from source

One-click deployment with Docker Compose:

1. Download the docker-compose.yml file: curl -L https://raw.githubusercontent.com/sdcb/csharp-runner/refs/heads/master/docker-compose.yml -o docker-compose.yml

2. Start the services in detached mode: docker compose up -d

3. Access the web UI (host) at: http://localhost:5050

Local development (advanced):

• Run Host service (from source): cd src/Sdcb.CSharpRunner.Host dotnet run

• Run Worker service (from source): cd src/Sdcb.CSharpRunner.Worker dotnet run

Customizing environment:

• Use the docker-compose.yml file to adjust replica counts and worker resource limits as shown in the Configuration section of the readme.
• You can scale the number of Worker containers with deploy.replicas and set environment variables like MaxRuns, Register, RegisterHostURL, WarmUp, and MaxTimeout.

Note: If you intend to build custom images, use the publish commands shown in the readme to publish the host and worker containers with ContainerRepository set to your desired image names.

Tips and considerations:

• The MCP endpoint is exposed at /mcp and supports the run_code tool for executing C# snippets.
• The HTTP API at /api/run streams output via SSE, including stdout, result, and errors.
• Worker containers support resource limits and can be recycled after a configured number of runs for a clean environment.
• Enable WarmUp in the worker environment to improve startup performance in standalone deployments.
• When deploying with docker-compose, you can scale workers by adjusting deploy.replicas and resource limits in the worker service.
• If you encounter network or registration issues, verify Register and RegisterHostUrl values and ensure the host can be reached from workers.
• The project supports a complete Docker Compose solution for quick deployment, as well as local development workflows if you want to run services individually.