# Docker Guide
> **Important License Notice**
>
> Stata® is a registered trademark and copyrighted software of StataCorp LLC. This project does **not** distribute Stata software.
>
> Our Docker images are built on top of the [AEA Data Editor's Stata images](https://github.com/AEADataEditor/docker-stata), which have been graciously provided with permission from StataCorp to distribute the Stata binaries (without license files).
>
> **You must possess a valid Stata license to use these images.** By using these Docker images, you agree to comply with StataCorp's [End-User License Agreement](https://www.stata.com/order/end-user-license-agreement/).
> **Note**: If you are not familiar with Docker, we recommend using Stata-MCP directly with `uvx stata-mcp` instead.
Stata-MCP provides official Docker images for running in sandboxed environments. This is useful for:
- **Isolation**: Run Stata-MCP without affecting your local environment
- **Reproducibility**: Consistent environment across different machines
- **Parallel Tasks**: Run multiple independent Stata tasks simultaneously
- **CI/CD**: Integrate Stata analysis into automated pipelines
## Prerequisites
- **Docker** installed and running
- **Stata license file** (`stata.lic`) - the only file you need to prepare
## Available Images
Stata-MCP images are available from two registries:
### GitHub Container Registry (Recommended)
```bash
docker pull ghcr.io/sepinetam/stata-mcp_19_5_mp:latest
```
### DockerHub (Alternative)
```bash
docker pull sepinetam/stata-mcp_19_5_mp:latest
```
### Image Naming Convention
```
stata-mcp_{VERSION}_{EDITION}
```
- **VERSION**: `19_5` (StataNow 19.5), `18_5` (StataNow 18.5), `18` (Stata 18)
- **EDITION**: `mp` (Multi-processor), `se` (Standard), `be` (Basic)
### Available Images
> The image which you chose is based on your Stata license.
| Image | Description |
|-------|-------------|
| `stata-mcp_19_5_mp` | StataNow 19.5 Multi-processor (recommended) |
| `stata-mcp_19_5_se` | StataNow 19.5 Standard |
| `stata-mcp_19_5_be` | StataNow 19.5 Basic |
| `stata-mcp_18_5_mp` | StataNow 18.5 Multi-processor |
| `stata-mcp_18_5_se` | StataNow 18.5 Standard |
| `stata-mcp_18_5_be` | StataNow 18.5 Basic |
| `stata-mcp_18_mp` | Stata 18 Multi-processor |
| `stata-mcp_18_se` | Stata 18 Standard |
| `stata-mcp_18_be` | Stata 18 Basic |
## Running Containers
### Basic Usage
```bash
docker run -i --rm \
-v /path/to/stata.lic:/usr/local/stata/stata.lic \
-v $(pwd):/workspace \
ghcr.io/sepinetam/stata-mcp_19_5_mp:latest
```
### Parameter Explanation
| Parameter | Description |
|-----------|-------------|
| `-i` | Interactive mode, keeps STDIN open |
| `--rm` | Automatically remove container when it exits |
| `-v /path/to/stata.lic:/usr/local/stata/stata.lic` | Mount your Stata license file |
| `-v $(pwd):/workspace` | Mount current directory as workspace |
### With Custom Working Directory
```bash
docker run -i --rm \
-v /path/to/stata.lic:/usr/local/stata/stata.lic \
-v /path/to/your/project:/workspace \
ghcr.io/sepinetam/stata-mcp_19_5_mp:latest
```
### Running in Background
For long-running tasks, you may want to run the container in background:
```bash
docker run -d --name stata-mcp-task \
-v /path/to/stata.lic:/usr/local/stata/stata.lic \
-v $(pwd):/workspace \
ghcr.io/sepinetam/stata-mcp_19_5_mp:latest
```
Check logs:
```bash
docker logs -f stata-mcp-task
```
Stop and remove:
```bash
docker stop stata-mcp-task
docker rm stata-mcp-task
```
## MCP Client Configuration
### General Configuration
To use the Docker image with MCP clients (Claude Code, Cursor, Cline, etc.), configure your MCP settings:
```json
{
"mcpServers": {
"stata-mcp": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v",
"/path/to/stata.lic:/usr/local/stata/stata.lic",
"-v",
"/path/to/workspace:/workspace",
"ghcr.io/sepinetam/stata-mcp_19_5_mp"
]
}
}
}
```
Replace:
- `/path/to/stata.lic` - Absolute path to your Stata license file
- `/path/to/workspace` - Absolute path to your working directory
### Claude Code CLI
Or use Claude Code CLI to add the Docker-based MCP server:
```bash
claude mcp add stata-mcp -s local -- docker run --rm -i \
-v /path/to/stata.lic:/usr/local/stata/stata.lic \
-v $(pwd):/workspace \
ghcr.io/sepinetam/stata-mcp_19_5_mp
```
### Install with Stata-MCP CLI
Or use the Stata-MCP CLI to install Docker-based MCP server:
```bash
uvx stata-mcp sandbox-install \
--version 19_5 \
--edition mp \
--tag latest \
-l /path/to/stata.lic \
-c claude
```
#### CLI Options
| Option | Default | Description |
|--------|---------|-------------|
| `-V, --version` | `19_5` | Stata version (`19_5`, `18_5`, `18`) |
| `-e, --edition` | `mp` | Stata edition (`mp`, `se`, `be`) |
| `--tag` | `latest` | Docker image tag |
| `-l, --license-file` | (required) | Path to Stata license file |
| `-c, --client` | `claude` | Target client (`claude`, `cc`, `cursor`, `cline`) |
| `--work-dir` | `./` | Working directory |
| `--cpus` | (none) | CPU core limit |
| `--memory` | (none) | Memory limit |
## Building from Source
If you want to build the image locally (mainly for developers):
```bash
# Clone the repository
git clone https://github.com/sepinetam/stata-mcp.git
cd stata-mcp
# Build with specific Stata version
docker build \
--build-arg CAPTURE_VERSION=19_5 \
--build-arg BASIS=mp \
-t stata-mcp:local .
```
### Build Arguments
| Argument | Default | Description |
|----------|---------|-------------|
| `CAPTURE_VERSION` | `19_5` | Stata version (`19_5`, `18_5`, `18`) |
| `BASIS` | `mp` | Stata edition (`mp`, `se`, `be`) |
| `TAG` | `2026-01-14` | AEA base image tag |
Note: Building locally still requires a valid Stata license at runtime.
## Tips
1. **License Security**: Keep your `stata.lic` file secure and never commit it to version control
2. **Data Persistence**: Always mount a workspace volume to persist your analysis results
3. **Resource Limits**: Use `--memory` and `--cpus` flags to limit container resources if needed:
```bash
docker run -i --rm --memory=4g --cpus=2 \
-v /path/to/stata.lic:/usr/local/stata/stata.lic \
-v $(pwd):/workspace \
ghcr.io/sepinetam/stata-mcp_19_5_mp:latest
```
## Troubleshooting
### License Not Found
```
Error: Stata license not found
```
Make sure the license file path is correct and the file exists.
### Permission Denied
```
Error: Permission denied accessing /workspace
```
On Linux, you may need to adjust file permissions or use `--user` flag.
### Container Exits Immediately
Check the logs for error messages:
```bash
docker logs <container_id>
```
