MCP Opener

Model Context Protocol server for opening files, folders, and browsers across different operating systems. Designed specifically to handle Linux Flatpak Firefox complexities on distributions like Fedora Bluefin.

Features

• Open Folders: Launch system file manager (Nautilus, Finder, Explorer, etc.)
• Open Files: Open files with their default applications
• Open Browser: Open URLs with configurable browser preferences
• Flatpak Firefox Support: Auto-detects and handles Flatpak Firefox installations
• Cross-Platform: Works on Linux, macOS, and Windows
• Smart File Handling: Automatically copies files to /tmp for Flatpak browser access when needed

Installation

# Install dependencies
pnpm install

# Build
pnpm build

# Install globally (optional)
pnpm link --global

Configuration

Configure via environment variables in your .env file or Claude Code MCP settings:

# 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

Add to your Claude Code MCP settings (.claude/settings.json or global 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"
      }
    }
  }
}

Or using pnpm:

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

Tools

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, falls back to nautilus or dolphin
• 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

This works around Flatpak's filesystem sandboxing restrictions.

Platform Support

Usage Examples

From Claude Code

User: Open my Downloads folder
Agent: [Uses open_folder tool with path: /home/user/Downloads]

User: Open this README file
Agent: [Uses open_file tool with path: ./README.md]

User: Open GitHub in my browser
Agent: [Uses open_browser tool with url: https://github.com]

User: Preview this HTML file
Agent: [Uses open_browser tool with url: file:///home/user/project/index.html]
      [On Flatpak Firefox: Copies to /tmp, opens copy, cleans up]

Direct Tool Calls

// Open folder
{
  "name": "open_folder",
  "arguments": {
    "path": "/home/viky/Code"
  }
}

// Open file
{
  "name": "open_file",
  "arguments": {
    "path": "./package.json"
  }
}

// Open browser
{
  "name": "open_browser",
  "arguments": {
    "url": "https://anthropic.com"
  }
}

Error Handling

The server provides detailed error messages:

• File/folder not found: "File does not exist: /path/to/file"
• Invalid URL: "URL must start with http://, https://, or file://"
• Platform not supported: "Unsupported platform: <platform>"
• No file manager found: "No file manager found (tried xdg-open, nautilus, dolphin)"

Development

# Watch mode for development
pnpm dev

# Build for production
pnpm build

# Test the server manually
echo '{"method":"tools/list"}' | node dist/index.js

Troubleshooting

Flatpak Firefox not detected

Check if Firefox is installed via Flatpak:

flatpak list --app | grep firefox

If installed, you should see org.mozilla.firefox. Set MCP_OPENER_FIREFOX_FLATPAK=true explicitly if auto-detection fails.

Files not opening in Flatpak Firefox

Ensure MCP_OPENER_TMP_COPY=true (default). The server will copy files to /tmp for Flatpak accessibility.

Wrong browser opens

Set MCP_OPENER_BROWSER explicitly:

MCP_OPENER_BROWSER=firefox
# or
MCP_OPENER_BROWSER=chrome
# or
MCP_OPENER_BROWSER=default

License

MIT

Author

3viky

Contributing

Issues and PRs welcome at github.com/3viky/mcp-opener