Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,16 @@ All notable changes to Inbrowse are recorded here. The format follows

## [Unreleased]

### Added

- `inbrowse mcp --allow-file-access` (or `INBROWSE_MCP_ALLOW_FILE_ACCESS=1`)
lets the MCP page tools open `file://` pages, such as a local HTML or SVG
file. Off by default, as before; the Claude Code plugin has an "Open local
files" setting for it.
- The Claude Code plugin has an "Open localhost and LAN pages" setting, so its
browser can load a local dev server such as `http://localhost:3000` (it sets
`INBROWSE_ALLOW_PRIVATE_NETWORK`). Off by default.

## [0.4.0] - 2026-11-12

### Added
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -622,6 +622,7 @@ Optional flags (both transports):
| `--font-dir <DIR>` | Load additional fonts before rendering (repeatable; render build) |
| `--stealth` | Enable anti-detection mode |
| `--idle-timeout <SECS>` | Close every page after this many seconds with no request (default `300`; `0` keeps pages open). Cookies and storage stay, and the next call opens a new page and says the old one was closed |
| `--allow-file-access` | Let `browser_navigate` and `browser_tab_new` open `file://` pages, such as a local HTML or SVG file. Off by default; `INBROWSE_MCP_ALLOW_FILE_ACCESS=1` does the same, and the Claude Code plugin has an "Open local files" setting for it |

### Claude Code plugin

Expand Down
75 changes: 72 additions & 3 deletions crates/inbrowse-cli/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -294,6 +294,14 @@ enum Command {
/// storage. 0 keeps pages open until `browser_close` or exit.
#[arg(long, value_name = "SECS", default_value_t = inbrowse_mcp::DEFAULT_IDLE_CLOSE.as_secs())]
idle_timeout: u64,

/// Let page tools (browser_navigate, browser_tab_new) open file://
/// URLs. Off by default so an agent cannot read local files through a
/// page. INBROWSE_MCP_ALLOW_FILE_ACCESS=1 does the same (the Claude
/// Code plugin sets it). With --http, any client that can reach the
/// server can then read this machine's files.
#[arg(long)]
allow_file_access: bool,
},

/// Print the text of a PDF, Word, PowerPoint, OpenDocument, spreadsheet,
Expand Down Expand Up @@ -561,6 +569,19 @@ fn merge_user_agent(
command_user_agent.or(global_user_agent)
}

/// Whether an on/off environment variable is on: `1`, `true`, `yes` or `on`,
/// in any case, the values `INBROWSE_ALLOW_PRIVATE_NETWORK` accepts
/// (inbrowse-ssrf `env_allows_private_network`). Used for
/// `INBROWSE_MCP_ALLOW_FILE_ACCESS`, which the Claude Code plugin sets.
fn env_flag_enabled(value: Option<&str>) -> bool {
value.is_some_and(|value| {
matches!(
value.trim().to_ascii_lowercase().as_str(),
"1" | "true" | "yes" | "on"
)
})
}

/// Normalize a raw `--v8-flags` value into the string we'll hand to V8.
/// Returns `None` when the user didn't pass the flag, passed an empty string,
/// or passed only whitespace; in those cases V8 is left untouched.
Expand Down Expand Up @@ -909,11 +930,18 @@ async fn run_cli() -> anyhow::Result<()> {
proxy,
user_agent,
idle_timeout,
allow_file_access,
}) => {
let user_agent = merge_user_agent(global_user_agent.clone(), user_agent);
configure_font_directories(&font_dirs)?;
let mcp_proxy = merge_proxy(global_proxy.clone(), proxy);
let idle_close = (idle_timeout > 0).then(|| Duration::from_secs(idle_timeout));
let allow_file_access = allow_file_access
|| env_flag_enabled(
std::env::var("INBROWSE_MCP_ALLOW_FILE_ACCESS")
.ok()
.as_deref(),
);
// `inbrowse mcp` builds its BrowserContext from the environment, so
// the global profile flag has to be handed over explicitly.
if let Some(ref dir) = global_storage_dir {
Expand All @@ -923,10 +951,25 @@ async fn run_cli() -> anyhow::Result<()> {
}
}
if http {
inbrowse_mcp::http::run(host, port, mcp_proxy, user_agent, stealth, idle_close)
.await?;
inbrowse_mcp::http::run(
host,
port,
mcp_proxy,
user_agent,
stealth,
idle_close,
allow_file_access,
)
.await?;
} else {
inbrowse_mcp::run(mcp_proxy, user_agent, stealth, idle_close).await?;
inbrowse_mcp::run(
mcp_proxy,
user_agent,
stealth,
idle_close,
allow_file_access,
)
.await?;
}
}
#[cfg(feature = "extract")]
Expand Down Expand Up @@ -4109,6 +4152,32 @@ mod tests {
}
}

#[test]
fn mcp_file_access_is_off_unless_asked_for() {
let parse = |extra: &[&str]| {
let mut argv = vec!["inbrowse", "mcp"];
argv.extend_from_slice(extra);
match Args::try_parse_from(argv)
.expect("clap should parse mcp")
.command
{
Some(Command::Mcp {
allow_file_access, ..
}) => allow_file_access,
_ => panic!("expected Mcp command"),
}
};
assert!(!parse(&[]));
assert!(parse(&["--allow-file-access"]));
for on in ["1", "true", "YES", " on "] {
assert!(super::env_flag_enabled(Some(on)), "{on}");
}
for off in ["", "0", "false", "off", "no", "2"] {
assert!(!super::env_flag_enabled(Some(off)), "{off}");
}
assert!(!super::env_flag_enabled(None));
}

#[test]
fn no_subcommand_is_not_quiet() {
assert!(!is_quiet_command(&None));
Expand Down
7 changes: 5 additions & 2 deletions crates/inbrowse-mcp/src/http.rs
Original file line number Diff line number Diff line change
Expand Up @@ -272,14 +272,17 @@ fn cors_header(origin: Option<&str>, allowlist: Option<&str>) -> String {
}

/// MCP Streamable HTTP transport (POST /mcp → JSON response). Pages open and
/// close for idleness as on stdio ([`crate::run`]).
/// close for idleness as on stdio ([`crate::run`]). `allow_file_access` lets
/// page tools open `file://` URLs, so any client that can reach the server can
/// read this machine's files: enable it only on a trusted network.
pub async fn run(
host: String,
port: u16,
proxy: Option<String>,
user_agent: Option<String>,
stealth: bool,
idle_close: Option<std::time::Duration>,
allow_file_access: bool,
) -> Result<()> {
let addr: std::net::SocketAddr = format!("{}:{}", host, port).parse()?;
let auth_token = token_from_env()?;
Expand All @@ -294,7 +297,7 @@ pub async fn run(
tracing::info!("MCP bearer authentication enabled");
}

let mut state = BrowserState::new(proxy, user_agent, stealth);
let mut state = BrowserState::with_file_access(proxy, user_agent, stealth, allow_file_access);
state.idle_close = idle_close;
let allowed_origins = Arc::new(allowed_origins_env());
let auth_token = Arc::new(auth_token);
Expand Down
58 changes: 51 additions & 7 deletions crates/inbrowse-mcp/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -130,13 +130,26 @@ pub struct BrowserState {

impl BrowserState {
pub fn new(proxy: Option<String>, user_agent: Option<String>, stealth: bool) -> Self {
Self::with_file_access(proxy, user_agent, stealth, false)
}

/// As [`Self::new`]; `allow_file_access` lets page tools open `file://`
/// URLs (`inbrowse mcp --allow-file-access`). Off by default so an agent
/// cannot read local files through a page. Callers: `run`, `http::run`.
pub fn with_file_access(
proxy: Option<String>,
user_agent: Option<String>,
stealth: bool,
allow_file_access: bool,
) -> Self {
// `--storage-dir` is a global flag, so the profile arrives through the
// environment rather than through every constructor call. Without this
// the MCP path silently ignored the flag and persisted nothing, cookies
// included.
let storage_dir = std::env::var_os("INBROWSE_STORAGE_DIR").map(std::path::PathBuf::from);
let context =
let mut context =
BrowserContext::with_storage_full("mcp".to_string(), proxy, stealth, None, storage_dir);
context.set_allow_file_access(allow_file_access);
BrowserState {
tabs: std::collections::BTreeMap::new(),
active_tab: None,
Expand Down Expand Up @@ -385,19 +398,21 @@ fn idle_duration_text(idle: Duration) -> String {

/// The stdio MCP server. The first tool call that needs a page opens one;
/// `idle_close` closes every page after that long with no request (`None`
/// keeps them until `browser_close` or exit).
/// keeps them until `browser_close` or exit). `allow_file_access` lets page
/// tools open `file://` URLs. Caller: inbrowse-cli `mcp`.
pub async fn run(
proxy: Option<String>,
user_agent: Option<String>,
stealth: bool,
idle_close: Option<Duration>,
allow_file_access: bool,
) -> Result<()> {
let stdin = tokio::io::stdin();
let stdout = tokio::io::stdout();
let mut reader = BufReader::new(stdin);
let mut writer = stdout;

let mut state = BrowserState::new(proxy, user_agent, stealth);
let mut state = BrowserState::with_file_access(proxy, user_agent, stealth, allow_file_access);
state.operator_network_hints = true;
// A stdio server runs as the local user's child process, so document_extract
// may read that user's files here (never on the HTTP transport).
Expand Down Expand Up @@ -1617,11 +1632,17 @@ async fn tool_navigate(args: &Value, state: &mut BrowserState) -> Result<String,
.get("url")
.and_then(Value::as_str)
.ok_or("Missing url parameter")?;
if url::Url::parse(url)
.ok()
.is_some_and(|parsed| parsed.scheme() == "file")
if !state.context.allow_file_access
&& url::Url::parse(url)
.ok()
.is_some_and(|parsed| parsed.scheme() == "file")
{
return Err("file:// navigation is disabled for MCP".to_string());
return Err(
"file:// navigation is disabled for MCP; start the server with \
`inbrowse mcp --allow-file-access` (or INBROWSE_MCP_ALLOW_FILE_ACCESS=1) \
to open local files"
.to_string(),
);
}
let wait_until = args
.get("waitUntil")
Expand Down Expand Up @@ -4628,6 +4649,29 @@ mod tests {
);
}

#[tokio::test(flavor = "current_thread")]
async fn file_navigation_follows_the_allow_file_access_switch() {
let dir = std::env::temp_dir().join(format!("inbrowse-mcp-file-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
let path = dir.join("page.html");
std::fs::write(&path, "<title>Local</title><p>from disk</p>").unwrap();
let url = url::Url::from_file_path(&path).unwrap().to_string();

// Off by default, and the refusal names the switch.
let mut closed = BrowserState::new(None, None, false);
let error = tool_navigate(&json!({ "url": url }), &mut closed)
.await
.expect_err("file:// must be refused by default");
assert!(error.contains("--allow-file-access"), "{error}");

let mut open = BrowserState::with_file_access(None, None, false, true);
let summary = tool_navigate(&json!({ "url": url }), &mut open)
.await
.expect("with the switch the local page opens");
assert!(summary.contains("\"Local\""), "{summary}");
std::fs::remove_dir_all(dir).unwrap();
}

/// The page for the select-field tests: a single select whose markup
/// default is not the first option, and a multiple select.
const SELECT_FORM_PAGE: &str = "<!doctype html><meta charset=utf-8>\
Expand Down
24 changes: 20 additions & 4 deletions crates/inbrowse-mcp/tests/cors_preflight.rs
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,16 @@ async fn browser_preflight_is_denied_without_an_origin_allowlist() {
// end of the test. `current_thread` + LocalSet is required because the
// browser state is `!Send` (Page holds V8 handles).
let server = local.spawn_local(async move {
let _ =
inbrowse_mcp::http::run("127.0.0.1".to_string(), port, None, None, false, None).await;
let _ = inbrowse_mcp::http::run(
"127.0.0.1".to_string(),
port,
None,
None,
false,
None,
false,
)
.await;
});

local.run_until(async {
Expand Down Expand Up @@ -75,8 +83,16 @@ async fn oversized_content_length_is_rejected() {
let local = LocalSet::new();

let server = local.spawn_local(async move {
let _ =
inbrowse_mcp::http::run("127.0.0.1".to_string(), port, None, None, false, None).await;
let _ = inbrowse_mcp::http::run(
"127.0.0.1".to_string(),
port,
None,
None,
false,
None,
false,
)
.await;
});

local
Expand Down
2 changes: 2 additions & 0 deletions crates/inbrowse-mcp/tests/http_page_progress.rs
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ async fn page_callbacks_progress_without_more_http_tool_calls() {
None,
false,
None,
false,
));
local.run_until(async {
for _ in 0..100 {
Expand Down Expand Up @@ -139,6 +140,7 @@ async fn idle_pages_close_and_the_next_call_says_so() {
None,
false,
Some(Duration::from_millis(500)),
false,
));
local.run_until(async {
for _ in 0..100 {
Expand Down
12 changes: 10 additions & 2 deletions crates/inbrowse-mcp/tests/sse_stream_does_not_wedge.rs
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,16 @@ async fn open_sse_stream_does_not_block_other_requests() {
let local = LocalSet::new();

let server = local.spawn_local(async move {
let _ =
inbrowse_mcp::http::run("127.0.0.1".to_string(), port, None, None, false, None).await;
let _ = inbrowse_mcp::http::run(
"127.0.0.1".to_string(),
port,
None,
None,
false,
None,
false,
)
.await;
});

local
Expand Down
2 changes: 2 additions & 0 deletions docs/CLI-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -224,6 +224,8 @@ Run inbrowse as an MCP server.
--proxy <URL> HTTP or SOCKS5 proxy
--user-agent <UA> Override the User-Agent
--idle-timeout <SECS> Close pages after this long with no request (default 300, 0 = never)
--allow-file-access Let page tools open file:// URLs (off by default;
INBROWSE_MCP_ALLOW_FILE_ACCESS=1 does the same)
--stealth Consistent browser fingerprint + tracker blocking (global)
--allow-private-network Permit loopback / RFC1918 / link-local
-v, --verbose Enable info logging
Expand Down
6 changes: 6 additions & 0 deletions docs/Use-the-MCP-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,12 @@ last page so the agent can navigate back. Change the wait with
`--idle-timeout <SECS>`; `--idle-timeout 0` keeps pages open until
`browser_close` or exit.

Local files: `browser_navigate` refuses `file://` URLs unless the server runs
with `--allow-file-access` (or `INBROWSE_MCP_ALLOW_FILE_ACCESS=1`; the Claude
Code plugin's "Open local files" setting sets it). With `--http`, any client
that can reach the server can then read this machine's files, so enable it
there only on a trusted network.

Navigation and lifecycle:

- `browser_navigate`, `browser_back`, `browser_forward`, `browser_reload`, `browser_close`
Expand Down
Loading