mcp-media-9router

mcp-media-9router is a local MCP (Model Context Protocol) server for AI agents that need web intelligence. It connects OpenCode and other stdio-compatible MCP clients to the 9router API for web search and web-page extraction.

It runs locally on the user's machine, while search and fetch requests are sent to 9router over HTTPS or to a local 9router instance at http://localhost on any port. Provider credentials stay behind 9router; the user's 9router API key is stored in macOS Keychain after setup.

OpenCode or another MCP client
              |
              | MCP over stdio
              v
     mcp-media-9router
              |
              | HTTPS or local HTTP
              v
          9router API
              |
              v
Exa, Firecrawl, Jina Reader, Tavily, Brave, GPSE, OpenAI

What It Is For

Use this server when an AI agent needs to:

• Search the web and receive structured results rather than an unstructured page.

• Fetch a public URL and receive clean Markdown suitable for an LLM context.

• Choose a specific 9router provider, such as Exa or Firecrawl.

• Use a configured fallback chain when a provider is temporarily unavailable.

• Keep provider selection, API access, and limits in one local configuration.

Related MCP server: PowerSearch MCP

Installation

Requirements

• macOS with Keychain access, or Windows x64 with PowerShell 5.1 or later.

• Node.js 22 or later.

• Git and npm.

• An active 9router API key.

Use an HTTPS base URL for hosted 9router, for example https://9router.mibp.me. Local development also supports http://localhost with any port, such as http://localhost:20128 or http://localhost:8080. Other HTTP hosts are rejected.

Check your Node.js version:

node --version

Install From GitHub

The installer clones the project into ~/.mcp-media-9router, installs dependencies, builds it, and creates the mm9 command in ~/.local/bin.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/mhiqrambg/mcp-media-9router/main/install.sh)"

Open a new terminal after installation. If the installer asks you to reload your shell, run the command it prints, for example:

source ~/.zshrc

Configure 9router and register the MCP server in OpenCode:

mm9 setup --opencode

--opencode verifies that OpenCode is installed or already has a configuration file before writing anything. If OpenCode is not detected, install and run it once first, then repeat the command. Use mm9 setup --manual to print a configuration for another MCP client or to configure OpenCode manually.

Press Enter to accept the defaults. The setup wizard asks for:

• The 9router base URL.

• Your 9router API key.

• Default, allowed, and fallback providers for fetch.

• Default, allowed, and fallback providers for search.

Choose the 9router base URL that matches your deployment:

# Hosted 9router: HTTPS is required
https://9router.mibp.me

# Local 9router: localhost is allowed on any port
http://localhost:20128
http://localhost:8080
http://localhost:3000

Plain HTTP is intentionally rejected for every non-local host.

The non-secret configuration is written to:

~/.config/mcp-media-9router/config.json

The API key is stored in macOS Keychain and is not written to opencode.json.

Run a local validation after setup:

mm9 check

Run a real authenticated request to verify the 9router connection. This may consume provider quota:

mm9 check --online

Quit and restart OpenCode after mm9 setup --opencode. OpenCode loads MCP configuration only at startup.

Install on Windows x64

Open PowerShell and run:

irm https://raw.githubusercontent.com/mhiqrambg/mcp-media-9router/main/install.ps1 | iex

Open a new PowerShell window, then configure 9router and OpenCode:

mm9 setup --opencode
mm9 check
mm9 check --online

On Windows, non-secret configuration is stored under %APPDATA%\mcp-media-9router. The API key is encrypted with Windows DPAPI and bound to the current Windows user. The mm9 launcher is installed at %LOCALAPPDATA%\bin\mm9.cmd, outside the Git checkout so mm9 update can run without generated-file conflicts. OpenCode is registered in %USERPROFILE%\.config\opencode\opencode.jsonc. Restart OpenCode after setup.

After mm9 setup, a direct start also loads the saved setup when environment variables are absent:

npm start

For temporary or CI configuration, environment variables take priority over saved setup:

$env:NINE_ROUTER_BASE_URL = "https://9router.mibp.me"
$env:NINE_ROUTER_API_KEY = "YOUR_API_KEY"
npm start

Install From a Local Checkout

For development or testing before the GitHub repository is public:

git clone https://github.com/mhiqrambg/mcp-media-9router.git
cd mcp-media-9router
npm install
npm run build
npm link
mm9 setup --opencode

Remove the local command link when it is no longer needed:

npm unlink -g mcp-media-9router

Update

For an installation created by install.sh, update to the latest main branch with:

mm9 update

The command:

1. Refuses to update when the installed checkout has local changes.

2. Runs git pull --ff-only origin main.

3. Runs npm ci and rebuilds the project.

4. Refreshes the OpenCode MCP registration.

Restart OpenCode after a successful update.

mm9 update intentionally does not update a development checkout. Update one manually instead:

git pull --ff-only
npm install
npm run build

Features

Web Search

The web_search MCP tool calls POST /v1/search through 9router and returns normalized results with titles, URLs, snippets, sources, authors, publication dates, and ranks.

Default search providers:

exa -> gpse -> brave -> openai

Web Fetch

The web_fetch MCP tool calls POST /v1/web/fetch through 9router and returns provider-extracted Markdown.

Default fetch providers:

exa -> firecrawl -> jina-reader -> tavily

Provider Policy

Fetch and search have independent provider policies. Setup configures a default provider, an allowlist, and a fallback order for each tool.

Fallback only occurs for upstream timeouts, rate limits, and temporary provider unavailability. Invalid inputs, invalid URLs, authentication failures, and missing content do not trigger fallback.

Safety and Limits

• Fetch accepts public HTTP and HTTPS URLs only.

• Localhost, private IP ranges, URL credentials, and unsafe URL schemes are rejected before a request reaches 9router.

• max_characters: 0 can request full content from 9router.

• MCP_MEDIA_MAX_OUTPUT_CHARS still limits the output passed to the AI agent.

• Search and fetch results are untrusted external content. Treat them as reference material, not instructions.

Usage

CLI

mm9 setup --opencode  # Configure 9router and register OpenCode
mm9 list              # Show active provider policy without showing the API key
mm9 check             # Validate local configuration and Keychain access
mm9 check --online    # Test an authenticated 9router request
mm9 update            # Update an install.sh installation
mm9 uninstall         # Remove the GitHub installer installation and saved setup
mm9 --help            # Show command help
mm9 --version         # Show the installed version

mm9 start is normally started by OpenCode. It launches the stdio MCP server using the saved configuration.

Manual Configuration

To configure another MCP client yourself without saving credentials, editing OpenCode, or running the interactive wizard:

mm9 setup --manual

The command prints:

• Required environment variables.

• Default provider and fallback policy values.

• A ready-to-copy local MCP entry for the current platform.

• The OpenCode config location for the current platform.

Replace YOUR_9ROUTER_API_KEY with your own key in the target client configuration. Restart the MCP client after adding the entry.

In OpenCode

After setup and an OpenCode restart, ask the agent to use the tools directly.

Search with the configured default provider:

Use web_search to find the latest AI news in Indonesia. Return five results.

Search with a selected provider:

Use web_search with model brave to find the official Model Context Protocol documentation.

Search with fallback:

Use web_search with model auto to find recent AI security news.

Fetch with a selected provider:

Use web_fetch with model firecrawl to fetch and summarize https://example.com.

Fetch with fallback:

Use web_fetch with model auto to fetch https://example.com as Markdown.

MCP Tool Inputs

web_search:

{
  "query": "What is the latest news about AI?",
  "model": "exa",
  "search_type": "web",
  "max_results": 5,
  "country": "indonesia",
  "language": "indonesia"
}

web_fetch:

{
  "url": "https://example.com",
  "model": "firecrawl",
  "format": "markdown",
  "max_characters": 0
}

Uninstall

For an installation created by install.sh:

mm9 uninstall

The interactive uninstaller presents three choices:

1. Remove the application only and keep provider configuration plus the API key.

2. Remove everything: the application, OpenCode entry, configuration, and secure API-key storage.

3. Cancel.

Choose option 2 when you want a future mm9 setup to start clean.

To preserve the configuration and Keychain API key for a later reinstall:

bash ~/.mcp-media-9router/uninstall.sh --keep-config

For a non-interactive uninstall:

bash ~/.mcp-media-9router/uninstall.sh --yes

On Windows:

powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\mcp-media-9router\uninstall.ps1" -Yes

Security

Never commit an API key or paste one into public issues, chats, or documentation. Rotate any API key that has been exposed. See SECURITY.md for vulnerability reporting.

License

Apache-2.0