# Monid MCP Server

MCP server for [Monid](https://monid.ai)'s TinyFish free web search & fetch API. Exposes `web_search` and `web_extract` tools to any MCP-compatible client (Claude Code, Cursor, VS Code, etc.).

**TinyFish is 100% free** — both search and fetch cost $0/call. No subscriptions, no per-call charges. Just a free Monid account for the API key.

## Features

- **web_search** — Search the live web with freshness filtering (60 min - 10 years)
- **web_extract** — Fetch and extract clean Markdown from up to 10 URLs
- **Free** — $0/call, no rate limits
- **Real content** — Returns actual web content, not LLM-generated summaries
- **JavaScript rendering** — Handles SPAs and dynamic content via Chromium

## Pricing

| Provider | Search cost | Extract cost |
|----------|-------------|--------------|
| SerpAPI | $25/1K calls | — |
| Tavily | $8/1K calls | $0.008/credit |
| Exa | $7/1K calls | $1/1K pages |
| Brave | $5/1K calls | — |
| **TinyFish (this server)** | **$0** | **$0** |

## Installation

### 1. Get a Monid API key

1. Create a free account at [app.monid.ai](https://app.monid.ai)
2. Go to [API Keys](https://app.monid.ai/access/api-keys) and generate a key
3. Copy the key (shown only once)

### 2. Install the server

```bash
pip install monid-mcp
```

Or install from source:

```bash
git clone https://github.com/ashafizullah/monid-mcp.git
cd monid-mcp
pip install -e .
```

### 3. Configure

Set environment variables:

```bash
export MONID_API_KEY="monid_live_..."
```

Or create a `.env` file:

```
MONID_API_KEY=monid_live_...
MONID_BASE_URL=https://api.monid.ai
MONID_TIMEOUT=60
MONID_MAX_FETCH_URLS=5
```

## Usage with Claude Code

Add to your `.claude/settings.json`:

```json
{
  "mcpServers": {
    "monid": {
      "command": "monid-mcp",
      "env": {
        "MONID_API_KEY": "monid_live_..."
      }
    }
  }
}
```

Or use the full path:

```json
{
  "mcpServers": {
    "monid": {
      "command": "python",
      "args": ["-m", "monid_mcp.server"],
      "env": {
        "MONID_API_KEY": "monid_live_..."
      }
    }
  }
}
```

Restart Claude Code. The `web_search` and `web_extract` tools will be available automatically.

## Usage with Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "monid": {
      "command": "monid-mcp",
      "env": {
        "MONID_API_KEY": "monid_live_..."
      }
    }
  }
}
```

## Usage with VS Code (Copilot)

Add to your VS Code settings:

```json
{
  "github.copilot.chat.mcpServers": {
    "monid": {
      "command": "monid-mcp",
      "env": {
        "MONID_API_KEY": "monid_live_..."
      }
    }
  }
}
```

## Tools

### web_search

Search the live web via TinyFish.

**Parameters:**
- `query` (string, required) — Search query
- `limit` (integer, optional) — Max results (1-20, default: 5)
- `recency_minutes` (integer, optional) — Freshness window in minutes

**Example:**
```
web_search(query="AI agent frameworks 2026", limit=10, recency_minutes=10080)
```

### web_extract

Fetch and extract clean Markdown from URLs.

**Parameters:**
- `urls` (array of strings, required) — URLs to fetch (max 10)

**Example:**
```
web_extract(urls=["https://example.com",https://another.com"])
```

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `MONID_API_KEY` | — | Your Monid API key (required) |
| `MONID_BASE_URL` | `https://api.monid.ai` | Monid API endpoint |
| `MONID_TIMEOUT` | `60` | Request timeout in seconds |
| `MONID_MAX_FETCH_URLS` | `5` | Max URLs per extract call (1-10) |

## Running the server directly

```bash
# With environment variable
export MONID_API_KEY="monid_live_..."
monid-mcp

# Or with .env file
monid-mcp

# Debug mode
monid-mcp --debug
```

## License

MIT © Adam Suchi Hafizullah