npm package: @lensscode/ohmygpt-serper-mcp
Description: Serper MCP Server - Google Search via Serper API (powered by OhMyGPT)
Author: lenspace
Latest version: 1.0.0

# OhMyGPT Serper MCP Server (Node.js/TypeScript)

Google Search via Serper API (powered by OhMyGPT) - MCP Server Implementation in TypeScript.

## Features

- ✅ Google search via Serper API
- ✅ Configurable geolocation and language
- ✅ Cache control
- ✅ Pagination support
- ✅ Formatted output (answer box, organic results, related searches)
- ✅ Zero rate limits (uses your own API key)
- ✅ Native Node.js implementation (no Python required)
- ✅ TypeScript for type safety

## Requirements

- Node.js 18.0.0 or higher
- Serper API key

## Installation

### Option 1: NPX (Recommended)

No installation needed! Just configure Claude Desktop and it will run via npx.

### Option 2: Global Install

```bash
npm install -g @lensscode/ohmygpt-serper-mcp
```

### Option 3: Local Development

```bash
cd serper-mcp-js
npm install
npm run build
```

## Claude Desktop Configuration

Add to your Claude Desktop config file:

### macOS
```bash
~/Library/Application\ Support/Claude/claude_desktop_config.json
```

### Linux
```bash
~/.config/Claude/claude_desktop_config.json
```

### Windows
```bash
%APPDATA%\Claude\claude_desktop_config.json
```

### NPX Configuration (Recommended)

```json
{
  "mcpServers": {
    "ohmygpt-serper": {
      "command": "npx",
      "args": ["-y", "@lensscode/ohmygpt-serper-mcp"],
      "env": {
        "SERPER_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Local Development Configuration

```json
{
  "mcpServers": {
    "ohmygpt-serper": {
      "command": "node",
      "args": ["/absolute/path/to/serper-mcp-js/build/index.js"],
      "env": {
        "SERPER_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Environment Variables

- `SERPER_API_KEY` (required) - Your Serper API key
- `SERPAPI_BASE_URL` (optional) - Custom API base URL (default: `https://api.ohmygpt.com`)

## Usage

Once configured, you can use the search tool in Claude Code:

```
search with "How to build an MCP server"
```

### Parameters

- `q` (required): Search query
- `cache` (optional): Cache control (default: 3)
- `gl` (optional): Geolocation code (e.g., "us", "cn")
- `hl` (optional): Language code (e.g., "en", "zh-CN")
- `page` (optional): Page number (default: 1)
- `num` (optional): Results per page, max 100 (default: 10, >10 costs double credits)

### Examples

Basic search:
```
search with "quantum computing"
```

Search with language and location:
```
search with "quantum computing" and hl="zh-CN" and gl="cn"
```

Get more results:
```
search with "python tutorials" and num=20
```

## Development

### Install Dependencies

```bash
npm install
```

### Build

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

This uses `tsx` to run TypeScript directly without building.

### Test Locally

```bash
# Set API key
export SERPER_API_KEY="your_api_key_here"

# Run server
npm run dev
```

## Project Structure

```
serper-mcp-js/
├── src/
│   ├── index.ts       # MCP server entry point
│   └── search.ts      # Serper API client
├── build/             # Compiled JavaScript (generated)
├── package.json       # NPM configuration
├── tsconfig.json      # TypeScript configuration
└── README.md          # This file
```

## API Credits

- Non-cached successful queries: 500 tokens/query
- Cached queries: FREE
- Results >10 per page: DOUBLE cost

## Troubleshooting

### Error: "API key not configured"
Make sure SERPER_API_KEY is set:
```bash
echo $SERPER_API_KEY  # should show your key
```

### Server not starting
Check Node.js version:
```bash
node --version  # should be >= 18.0.0
```

### NPX not found
Make sure npm is installed and up to date:
```bash
npm --version
npm install -g npm@latest
```

## Comparison with Python Version

| Feature | Python | Node.js |
|---------|--------|---------|
| Runtime | Python 3.10+ | Node.js 18+ |
| Dependencies | mcp, httpx, pydantic | @modelcontextprotocol/sdk |
| Installation | pip install | npm install or npx |
| Type Safety | Optional (with mypy) | Built-in (TypeScript) |
| SSE Mode | ✅ Supported | 🔄 Future |
| Docker | ✅ Supported | ✅ Supported |

## License

MIT

## Links

- [MCP Documentation](https://modelcontextprotocol.io/)
- [Serper API](https://serper.dev/)
- [Python Version](../serper-mcp/)