https://github.com/3p3r/oatmeal
Oatmeal is a single binary tray application that extends your web agent's capabilities via an MCP server with browser automation, Bash, Python, and other automation utilities.
https://github.com/3p3r/oatmeal
agent-browser mcp mcp-server page-agent
Last synced: about 2 months ago
JSON representation
Oatmeal is a single binary tray application that extends your web agent's capabilities via an MCP server with browser automation, Bash, Python, and other automation utilities.
- Host: GitHub
- URL: https://github.com/3p3r/oatmeal
- Owner: 3p3r
- License: mit
- Created: 2026-03-05T17:51:26.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T08:19:24.000Z (2 months ago)
- Last Synced: 2026-03-31T10:21:20.335Z (2 months ago)
- Topics: agent-browser, mcp, mcp-server, page-agent
- Language: Rust
- Homepage: https://3p3r.github.io/oatmeal/
- Size: 624 KB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Oatmeal
Oatmeal is a single binary tray application that extends your web agent's capabilities via an MCP server with browser automation, Bash, Python, and other automation utilities.
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Command Mode](#command-mode)
- [Exporting Files from Command Mode](#exporting-files-from-command-mode)
- [MCP Tools](#mcp-tools)
- [CLI Equivalents](#cli-equivalents)
- [URI Launch Mode](#uri-launch-mode)
- [Platform Notes](#platform-notes)
## Quick Start
Oatmeal is meant to be used with its complementary barebones React component: [Storybook here](https://3p3r.github.io/oatmeal/storybook/). Build on top of this foundation to create your own custom agent interfaces, or use the MCP server directly in your agents without a UI.
Download the latest binary from [releases](https://github.com/3p3r/oatmeal/releases):
- Linux: `oatmeal-linux`
- macOS: `oatmeal-mac`
- Windows: `oatmeal-windows.exe`
Run it:
```bash
# Linux/macOS
chmod +x ./oatmeal-*
./oatmeal-*
# Windows
.\oatmeal-windows.exe
```
By default, Oatmeal starts an MCP server on `http://localhost:9607/mcp`.
macOS note:
```bash
xattr -d com.apple.quarantine ./oatmeal-mac
```
Windows note:
You may need to allow the binary through SmartScreen or Windows Defender the first time you run it.
## Configuration
Oatmeal works without configuration. Default behavior:
- Host: `0.0.0.0`
- Port: `9607`
- Browser path: auto-detected
- Page-agent model: `qwen3.5-plus`
- Page-agent URL: `http://localhost:11434/v1`
- Page-agent key: `NA`
Optional config sources:
- `~/.oatmeal`
- `./.oatmeal`
- `OATMEAL_*` environment variables
- CLI flags
Example config:
```toml
port = 9607
host = "0.0.0.0"
browser_path = "/path/to/browser"
[page_agent]
model = "qwen3.5-plus"
url = "http://localhost:11434/v1"
key = "NA"
```
Nested page-agent environment variables use double underscores:
- `OATMEAL_PAGE_AGENT__MODEL`
- `OATMEAL_PAGE_AGENT__URL`
- `OATMEAL_PAGE_AGENT__KEY`
Precedence is:
`built-in defaults -> ~/.oatmeal -> ./.oatmeal -> OATMEAL_* -> CLI flags`
## Command Mode
Use `--command` when you want to run a shell-style script instead of starting the MCP server.
Inside command mode, both `agent-browser` and the shorter `ab` alias are available.
Examples:
```bash
./oatmeal-* --command "agent-browser open https://example.com"
./oatmeal-* --command "ab open https://example.com"
./oatmeal-* --command "ab --headed open https://example.com"
./oatmeal-* --command "name=world && echo hello-$name > /report.txt"
./oatmeal-* --command "python3 -c \"print(2 ** 10)\""
```
Synthetic browser helpers are also supported:
```bash
./oatmeal-* --command "ab agentic-open https://example.com"
./oatmeal-* --command "ab agentic-prompt https://example.com 'summarize this page'"
./oatmeal-* --command "ab agentic-prompt 'find the primary CTA on the current page'"
```
## Exporting Files from Command Mode
Oatmeal detects files created during command execution with a best-effort algorithm and captures them into MCP resources automatically.
## MCP Tools
When Oatmeal is running as an MCP server, it exposes these tools:
- `health`
- `version`
- `cache_directory`
- `screenshot_system`
- `shell_command`
- `delete_resource`
- `delete_all_resources`
- `uri_scheme`
- `shutdown`
User-facing behavior:
- `shell_command` runs the same script surface as CLI `--command`
- files generated by MCP command execution are returned as MCP resources
- `cache_directory` returns the cache folder used by Oatmeal, agents can use this to pass to `agent-browser` for file downloads
- `screenshot_system` captures all attached monitors as image resources
- `delete_resource` and `delete_all_resources` clean up generated resources from the current server
## CLI Equivalents
Standalone CLI flags expose the same functionality as the corresponding MCP tools:
| MCP Tool | CLI Flag | Output |
|----------|----------|--------|
| `version` | `--version-json` | `{"version": "X.Y.Z"}` |
| `cache_directory` | `--cache-dir` | `{"cache_dir": "..."}` |
| `screenshot_system` | `--screenshot` | saves PNGs to cache dir, prints paths as JSON |
| `shell_command` | `--command` | stdout/stderr passthrough |
| `uri_scheme register` | `--register-uri` | confirmation text |
| `uri_scheme unregister` | `--unregister-uri` | confirmation text |
## URI Launch Mode
Oatmeal supports an `oatmeal://` URI handler.
You can register or remove it explicitly:
```bash
./oatmeal-* --register-uri
./oatmeal-* --unregister-uri
```
When Oatmeal starts in default HTTP mode, it will register the URI handler automatically if needed.
Example URIs:
- `oatmeal://open?port=9911`
- `oatmeal://open?port=9911&host=127.0.0.1`
## Platform Notes
- Linux: x86_64 + aarch64
- macOS: universal binary
- Windows: 64-bit executable