Metadata-Version: 2.5
Name: serphubapi-mcp
Version: 0.1.0
Summary: MCP server for SerpHubAPI: web search and page fetch for AI agents
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.3
Description-Content-Type: text/markdown

# serphubapi-mcp

MCP server for [SerpHubAPI](https://serphubapi.com): give your agent one tool for many search services — Google / Bing / Yandex, AI search like DeepSeek, and more — plus clean page content in Markdown. `list_services` shows what is available and what it costs.

## Tools

| Tool | What it does | Credits |
|---|---|---|
| `search` | Multi-engine search, returned as Markdown. `include_content=N` also returns the full text of the top N pages. | 10 (live) / 5 (cache_first, 0 on hit) + 3 per page of content |
| `fetch` | Any public URL → main content as Markdown. | 3 (0 on failure) |

Failed calls and empty results are never charged.

## Setup

Get an API key at https://serphubapi.com/dashboard/keys (new accounts get 1,000 free credits).

### Claude Code

```bash
claude mcp add serphubapi -e SERPHUBAPI_API_KEY=shapi_xxx -- uvx serphubapi-mcp
```

### Cursor / Claude Desktop / other MCP clients

```json
{
  "mcpServers": {
    "serphubapi": {
      "command": "uvx",
      "args": ["serphubapi-mcp"],
      "env": { "SERPHUBAPI_API_KEY": "shapi_xxx" }
    }
  }
}
```

Cursor: `~/.cursor/mcp.json`. Claude Desktop: `claude_desktop_config.json`.

### Environment

| Variable | Default | |
|---|---|---|
| `SERPHUBAPI_API_KEY` | — | required |
| `SERPHUBAPI_BASE_URL` | `https://api.serphubapi.com` | override for self-hosted / staging |

## Development

```bash
uv sync
uv run pytest
SERPHUBAPI_API_KEY=... uv run serphubapi-mcp   # stdio
```
