From 0358e6c26ae851026a0d5353574481eed2d01199 Mon Sep 17 00:00:00 2001
From: blockmandev <194144408+blockmandev@users.noreply.github.com>
Date: Thu, 12 Nov 2026 16:51:59 -0600
Subject: [PATCH] mcp: open local files and localhost pages when asked
inbrowse mcp --allow-file-access (or INBROWSE_MCP_ALLOW_FILE_ACCESS=1) lets
the page tools open file:// pages; off by default, and the refusal now names
the switch. The Claude Code plugin gains "Open local files" and "Open
localhost and LAN pages" settings, which set those variables.
---
CHANGELOG.md | 10 +++
README.md | 1 +
crates/inbrowse-cli/src/main.rs | 75 ++++++++++++++++++-
crates/inbrowse-mcp/src/http.rs | 7 +-
crates/inbrowse-mcp/src/lib.rs | 58 ++++++++++++--
crates/inbrowse-mcp/tests/cors_preflight.rs | 24 +++++-
.../inbrowse-mcp/tests/http_page_progress.rs | 2 +
.../tests/sse_stream_does_not_wedge.rs | 12 ++-
docs/CLI-reference.md | 2 +
docs/Use-the-MCP-server.md | 6 ++
plugin/inbrowse/.claude-plugin/plugin.json | 18 ++++-
11 files changed, 195 insertions(+), 20 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 132e0ac..f5d36b9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -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
diff --git a/README.md b/README.md
index 1ef3225..aa2f393 100644
--- a/README.md
+++ b/README.md
@@ -622,6 +622,7 @@ Optional flags (both transports):
| `--font-dir
` | Load additional fonts before rendering (repeatable; render build) |
| `--stealth` | Enable anti-detection mode |
| `--idle-timeout ` | 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
diff --git a/crates/inbrowse-cli/src/main.rs b/crates/inbrowse-cli/src/main.rs
index 7131b19..9ac1387 100644
--- a/crates/inbrowse-cli/src/main.rs
+++ b/crates/inbrowse-cli/src/main.rs
@@ -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,
@@ -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.
@@ -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 {
@@ -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")]
@@ -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));
diff --git a/crates/inbrowse-mcp/src/http.rs b/crates/inbrowse-mcp/src/http.rs
index ac09a28..6e74251 100644
--- a/crates/inbrowse-mcp/src/http.rs
+++ b/crates/inbrowse-mcp/src/http.rs
@@ -272,7 +272,9 @@ 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,
@@ -280,6 +282,7 @@ pub async fn run(
user_agent: Option,
stealth: bool,
idle_close: Option,
+ allow_file_access: bool,
) -> Result<()> {
let addr: std::net::SocketAddr = format!("{}:{}", host, port).parse()?;
let auth_token = token_from_env()?;
@@ -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);
diff --git a/crates/inbrowse-mcp/src/lib.rs b/crates/inbrowse-mcp/src/lib.rs
index 92918d7..67c0337 100644
--- a/crates/inbrowse-mcp/src/lib.rs
+++ b/crates/inbrowse-mcp/src/lib.rs
@@ -130,13 +130,26 @@ pub struct BrowserState {
impl BrowserState {
pub fn new(proxy: Option, user_agent: Option, 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,
+ user_agent: Option,
+ 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,
@@ -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,
user_agent: Option,
stealth: bool,
idle_close: Option,
+ 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).
@@ -1617,11 +1632,17 @@ async fn tool_navigate(args: &Value, state: &mut BrowserState) -> ResultLocalfrom disk
").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 = "\
diff --git a/crates/inbrowse-mcp/tests/cors_preflight.rs b/crates/inbrowse-mcp/tests/cors_preflight.rs
index 3330d2d..007d280 100644
--- a/crates/inbrowse-mcp/tests/cors_preflight.rs
+++ b/crates/inbrowse-mcp/tests/cors_preflight.rs
@@ -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 {
@@ -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
diff --git a/crates/inbrowse-mcp/tests/http_page_progress.rs b/crates/inbrowse-mcp/tests/http_page_progress.rs
index 76541a7..042e0b6 100644
--- a/crates/inbrowse-mcp/tests/http_page_progress.rs
+++ b/crates/inbrowse-mcp/tests/http_page_progress.rs
@@ -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 {
@@ -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 {
diff --git a/crates/inbrowse-mcp/tests/sse_stream_does_not_wedge.rs b/crates/inbrowse-mcp/tests/sse_stream_does_not_wedge.rs
index 9837ce2..b13651b 100644
--- a/crates/inbrowse-mcp/tests/sse_stream_does_not_wedge.rs
+++ b/crates/inbrowse-mcp/tests/sse_stream_does_not_wedge.rs
@@ -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
diff --git a/docs/CLI-reference.md b/docs/CLI-reference.md
index b2c8ab8..96c4b8e 100644
--- a/docs/CLI-reference.md
+++ b/docs/CLI-reference.md
@@ -224,6 +224,8 @@ Run inbrowse as an MCP server.
--proxy HTTP or SOCKS5 proxy
--user-agent Override the User-Agent
--idle-timeout 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
diff --git a/docs/Use-the-MCP-server.md b/docs/Use-the-MCP-server.md
index 53954e6..71ff7c2 100644
--- a/docs/Use-the-MCP-server.md
+++ b/docs/Use-the-MCP-server.md
@@ -70,6 +70,12 @@ last page so the agent can navigate back. Change the wait with
`--idle-timeout `; `--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`
diff --git a/plugin/inbrowse/.claude-plugin/plugin.json b/plugin/inbrowse/.claude-plugin/plugin.json
index 1b09598..edb278f 100644
--- a/plugin/inbrowse/.claude-plugin/plugin.json
+++ b/plugin/inbrowse/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "inbrowse",
"displayName": "Inbrowse",
- "version": "0.4.0",
+ "version": "0.4.1",
"description": "A fast headless browser for Claude Code: pages with JavaScript, forms and tabs; PDF, Office and spreadsheet text; video frames, audio and captions; OCR; research posts from Reddit, X, Hacker News, GitHub and Polymarket",
"author": { "name": "Incord AI", "url": "https://github.com/incordai" },
"homepage": "https://github.com/incordai/Inbrowse",
@@ -14,7 +14,9 @@
"args": ["mcp"],
"env": {
"INBROWSE_OCR_URL": "${user_config.ocr_url}",
- "INBROWSE_OCR_KEY": "${user_config.ocr_key}"
+ "INBROWSE_OCR_KEY": "${user_config.ocr_key}",
+ "INBROWSE_MCP_ALLOW_FILE_ACCESS": "${user_config.allow_file_access}",
+ "INBROWSE_ALLOW_PRIVATE_NETWORK": "${user_config.allow_private_network}"
}
}
},
@@ -37,6 +39,18 @@
"description": "Key for the OCR engine, only if it asks for one. Stored in the system's secure storage.",
"sensitive": true
},
+ "allow_file_access": {
+ "type": "boolean",
+ "title": "Open local files",
+ "description": "Let browser_navigate open file:// pages on this computer, such as a local HTML or SVG file. Off: only web pages. Needs Inbrowse 0.4.1 or later.",
+ "default": false
+ },
+ "allow_private_network": {
+ "type": "boolean",
+ "title": "Open localhost and LAN pages",
+ "description": "Let the browser load localhost, 127.0.0.1 and private-network addresses, such as a dev server at http://localhost:3000. Off: they are blocked, so a web page cannot reach your machine or network.",
+ "default": false
+ },
"route_webfetch": {
"type": "boolean",
"title": "Read WebFetch through Inbrowse",