Content
# 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.
```text
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:
```bash
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`.
```bash
/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:
```bash
source ~/.zshrc
```
Configure 9router and register the MCP server in OpenCode:
```bash
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:
```text
# 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:
```text
~/.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:
```bash
mm9 check
```
Run a real authenticated request to verify the 9router connection. This may consume provider quota:
```bash
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:
```bash
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:
```bash
npm unlink -g mcp-media-9router
```
## Update
For an installation created by `install.sh`, update to the latest `main` branch with:
```bash
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:
```bash
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:
```text
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:
```text
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
```bash
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:
```text
Use web_search to find the latest AI news in Indonesia. Return five results.
```
Search with a selected provider:
```text
Use web_search with model brave to find the official Model Context Protocol documentation.
```
Search with fallback:
```text
Use web_search with model auto to find recent AI security news.
```
Fetch with a selected provider:
```text
Use web_fetch with model firecrawl to fetch and summarize https://example.com.
```
Fetch with fallback:
```text
Use web_fetch with model auto to fetch https://example.com as Markdown.
```
### MCP Tool Inputs
`web_search`:
```json
{
"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`:
```json
{
"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`:
```bash
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
bash ~/.mcp-media-9router/uninstall.sh --keep-config
```
For a non-interactive uninstall:
```bash
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](./SECURITY.md) for vulnerability reporting.
## License
[Apache-2.0](./LICENSE)
