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.

Installation

Requirements

• macOS with Keychain access.
• 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

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 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.

Requested model	Behavior
Omitted	Uses the configured default provider once.
Specific provider	Uses that provider once. It must be on the relevant allowlist.
auto	Tries configured fallback providers in order.

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.

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"
}

Field	Required	Description
query	Yes	Search query, from 1 to 500 characters.
model	No	An allowed search provider, or auto.
search_type	No	9router search type. Default: web.
max_results	No	Result count from 1 to 20. Default: 5.
country	No	Country preference forwarded to 9router.
language	No	Language preference forwarded to 9router.

web_fetch:

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

Field	Required	Description
url	Yes	A public HTTP or HTTPS URL.
model	No	An allowed fetch provider, or auto.
format	No	Only markdown is currently supported.
max_characters	No	Maximum characters requested from 9router. 0 requests full content.

Uninstall

For an installation created by install.sh:

mm9 uninstall

The interactive uninstaller removes the mm9 launcher, ~/.mcp-media-9router, the media-9router OpenCode entry, the provider configuration, and the macOS Keychain API key. A later mm9 setup therefore starts with a clean setup.

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

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