MCP Opener MCP Server

How to use

You use MCP Opener by running a local MCP server that your Claude Code MCP client can talk to. The server exposes tools to open a folder, open a file, or open a URL in your preferred browser. In practice, you invoke these tools from your MCP client or any environment that can call the MCP tools directly.

How to install

Prerequisites you need before installing: - Node.js (recommended LTS version) - pnpm package manager Install dependencies, build, and optionally expose the server globally with the following steps.

# Install dependencies
pnpm install

# Build the MCP Opener bundle
pnpm build

# Install globally for easy access (optional)
pnpm link --global

Configuration and runtime

Configure the server using environment variables in your .env file or within Claude Code MCP settings. The main options are the preferred browser, Flatpak Firefox handling, and temporary copy behavior for Flatpak file access.

# Preferred browser: 'firefox' | 'chrome' | 'chromium' | 'default'
MCP_OPENER_BROWSER=firefox

# Explicitly set if Firefox is installed via Flatpak (auto-detected if omitted)
MCP_OPENER_FIREFOX_FLATPAK=true

# Whether to copy files to /tmp for Flatpak access (default: true)
MCP_OPENER_TMP_COPY=true

Claude Code configuration (stdio MCP server)

You can configure a local MCP server that runs with a standard Node.js process or via pnpm. Use either command in your Claude Code MCP settings.

{
  "mcpServers": {
    "opener": {
      "command": "node",
      "args": ["/path/to/mcp-opener/dist/index.js"],
      "env": {
        "MCP_OPENER_BROWSER": "firefox",
        "MCP_OPENER_FIREFOX_FLATPAK": "true",
        "MCP_OPENER_TMP_COPY": "true"
      }
    }
  }
}

Claude Code configuration via pnpm

If you prefer to start the server through pnpm, use this configuration.

{
  "mcpServers": {
    "opener": {
      "command": "pnpm",
      "args": ["--dir", "/path/to/mcp-opener", "exec", "node", "dist/index.js"],
      "env": {
        "MCP_OPENER_BROWSER": "firefox"
      }
    }
  }
}

Tools

MCP Opener provides three primary tools to integrate with your workflow.

### open_folder
Opens a folder in the system file manager.

Parameters:
- path (string, required): Absolute or relative path to the folder

Example:
{
  "path": "/home/user/Documents"
}

Behavior by Platform:
- Linux: Uses xdg-open, or navigates to Nautilus/Dolphin if needed
- macOS: Uses open (Finder)
- Windows: Uses explorer

open_file

Opens a file with its default application.

Parameters:
- path (string, required): Absolute or relative path to the file

Example:
{
  "path": "./report.pdf"
}

Behavior by Platform:
- Linux: Uses xdg-open
- macOS: Uses open
- Windows: Uses start

open_browser

Opens a URL in the preferred web browser.

Parameters:
- url (string, required): URL to open (must start with http://, https://, or file://)

Example:
{
  "url": "https://github.com"
}

Behavior:
1. Checks configured browser preference (MCP_OPENER_BROWSER)
2. On Linux with Firefox:
   - Auto-detects Flatpak installation
   - For file:// URLs with Flatpak: Copies file to /tmp for accessibility
   - Uses flatpak run org.mozilla.firefox for Flatpak
   - Uses native firefox command otherwise
3. Falls back to system default browser if preferred browser unavailable

Special Handling for Fedora Bluefin / Flatpak Firefox:
When opening local HTML files or other file:// URLs with Flatpak Firefox:
1. File is copied to /tmp/mcp-opener-<random>/
2. Browser opens the /tmp copy
3. Cleanup happens after 5 seconds

open_folder

Opens a folder in the system file manager with platform-specific behavior.

open_file

Opens a file with its default application across platforms.

open_browser

Opens a URL in the configured browser with special handling for Flatpak Firefox on Linux.