# JustSerpAPI MCP Server

Use JustSerpAPI from Codex, Claude Desktop, Cursor, and other MCP-compatible AI
assistants.

This MCP server helps your assistant find the right JustSerpAPI endpoint, inspect
the required parameters, call the API, and continue paginated results when the
API returns a next-page token or offset.

## Quick Start

### Remote HTTP

Remote HTTP is the recommended setup.

```json
{
  "mcpServers": {
    "justserpapi": {
      "url": "https://mcp.justserpapi.com/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}
```

### Local stdio

You can also run the MCP server locally with `npx`.

```json
{
  "mcpServers": {
    "justserpapi": {
      "command": "npx",
      "args": ["-y", "justserpapi-mcp"],
      "env": {
        "JUSTSERPAPI_API_KEY": "your_api_key"
      }
    }
  }
}
```

## Supported Clients

JustSerpAPI MCP works with MCP-compatible clients that support remote HTTP or
local stdio servers, including:

- Codex
- Claude Desktop
- Cursor
- Claude Code
- OpenAI Agents SDK
- Other MCP-compatible AI assistants

## Authentication

Use your JustSerpAPI API key:

```text
Authorization: Bearer your_api_key
```

For local stdio, set:

```text
JUSTSERPAPI_API_KEY=your_api_key
```

## Available Tools

- `search_endpoints`: Find the best JustSerpAPI endpoint from a natural-language request.
- `get_endpoint_schema`: Inspect required parameters, optional parameters, and pagination hints.
- `call_endpoint`: Call a JustSerpAPI endpoint and return raw JSON data.
- `get_account_balance`: Check your subscription and remaining credits.
- `get_usage_summary`: Review recent API usage, consumed credits, and endpoint trends.
- `list_services`: List available services such as Google Search, Google Maps, Google Trends, and Web.
- `refresh_catalog`: Refresh the endpoint catalog from JustSerpAPI docs.

## Example Prompts

Ask your AI assistant naturally:

```text
Find the Google search API and show me the required parameters.
```

```text
Search Google for "best running shoes" in the United States.
```

```text
Find the Google Maps reviews endpoint and tell me how to request the next page.
```

```text
Get Google Trends trending-now results for the US.
```

```text
Find the Google Shopping search API and call it for "iphone 16 case".
```

```text
Convert this web page to Markdown: https://example.com
```

```text
Continue to the next page of the previous JustSerpAPI result.
```

```text
Check my remaining JustSerpAPI credits.
```

```text
Show my API usage for the last 30 days.
```

```text
The API returned code 402. Explain what it means and what I should check.
```

## Response Format

`call_endpoint` returns the JustSerpAPI response data as raw JSON. Large arrays
and long text fields may be shortened so the AI assistant can read the result
reliably. When that happens, the response includes `truncated: true` and the
paths that were shortened.

## License

MIT