# @zapifyapi/mcp-server

Official [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server for **ZapifyAPI** — gives AI agents access to 32 agent-ready tools across image conversion, text analysis, network diagnostics, developer utilities, and data conversion.

Selected from ZapifyAPI's catalogue of 40+ APIs: the tools exposed here are the ones that work well under agent control, with inputs a model can construct and outputs it can reason about.

## Quick Start

### 1. Get your MCP token

1. Sign up at [zapifyapi.com](https://zapifyapi.com) (free)
2. Go to **Dashboard → MCP**
3. Create an MCP token (choose permissions and spending limits)
4. Copy the token (starts with `mcp_`)

### 2. Add to your AI client

#### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "zapifyapi": {
      "command": "npx",
      "args": ["@zapifyapi/mcp-server"],
      "env": {
        "ZAPIFYAPI_TOKEN": "mcp_your_token_here"
      }
    }
  }
}
```

#### Kiro

Add to `.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "zapifyapi": {
      "command": "npx",
      "args": ["@zapifyapi/mcp-server"],
      "env": {
        "ZAPIFYAPI_TOKEN": "mcp_your_token_here"
      }
    }
  }
}
```

#### Local development

```bash
ZAPIFYAPI_TOKEN=mcp_your_token_here npx @zapifyapi/mcp-server
```

## Available Tools (32)

### Image & Media
- `convert_image_to_webp` — Convert PNG/JPEG to WebP
- `add_watermark` — Add text watermark to image

### Text & Language
- `translate_text` — Translate between 50+ languages
- `analyze_sentiment` — Detect tone (positive/negative/neutral)
- `extract_keywords` — Extract keywords with relevance scores
- `check_profanity` — Detect and censor profanity
- `validate_email` — Validate email format
- `parse_user_agent` — Parse UA into components

### Network & Security
- `ip_geolocation` — Locate an IP address
- `dns_lookup` — Query DNS records (A, MX, TXT, etc)
- `check_ssl` — Check SSL cert validity and expiry
- `scan_ports` — Scan open ports on a host
- `whois_lookup` — Domain WHOIS data
- `http_headers` — Fetch response headers for a URL

### Developer Tools
- `generate_qr_code` — QR code from text/URL
- `generate_password` — Secure random passwords
- `generate_hash` — MD5/SHA1/SHA256/SHA512
- `validate_json` — Validate and prettify JSON
- `generate_uuid` — Random v4 UUIDs
- `decode_jwt` — Decode JWT payload
- `test_regex` — Test regex against text
- `convert_color` — HEX/RGB/HSL conversion
- `base64_encode_decode` — Base64 encode/decode
- `markdown_to_html` — Markdown to HTML

### Data & Conversion
- `convert_currency` — Real-time currency rates
- `convert_units` — Length, weight, temperature
- `convert_timezone` — Time between zones
- `csv_to_json` — Parse CSV to JSON
- `extract_url_metadata` — Title, OG tags from URL
- `get_country_info` — Country details

### Fun
- `get_random_joke` — Programming jokes
- `get_random_quote` — Tech quotes

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ZAPIFYAPI_TOKEN` | Yes | Your MCP token (get from dashboard) |
| `ZAPIFYAPI_URL` | No | API base URL (default: `https://api.zapifyapi.com`) |

## How It Works

1. Your AI agent connects to this MCP server via stdio
2. Agent discovers tools via `tools/list`
3. Agent calls a tool (e.g., `dns_lookup` with `{ domain: "google.com" }`)
4. This server sends a POST to `https://api.zapifyapi.com/v1/<your_token>` with `{ _tool: "dns lookup", domain: "google.com" }`
5. The gateway routes to the correct API handler and returns results
6. Points are deducted from your project balance

### Responses

JSON results are returned as text content. Binary results — converted images, QR codes — are returned as native MCP `image` content, base64-encoded with the correct MIME type, so the agent receives the actual file rather than a description of it.

### Errors and retries

Rate-limited requests (HTTP 429) are retried up to three times with exponential backoff and jitter. If the retries are exhausted, or any other error occurs, the error message includes your remaining point balance where the API reports it, so the agent can tell you why a call failed.

## Security

- Your token is read from the `ZAPIFYAPI_TOKEN` environment variable and is never accepted as a tool argument, so a model cannot be prompted into echoing it into a transcript.
- The server makes no network calls other than to your configured `ZAPIFYAPI_URL`.
- Scope each MCP token in the dashboard to the APIs you actually want the agent to reach, and set a spending limit. Treat an MCP token like any other credential.

## Token Permissions

When creating an MCP token in the dashboard, you can configure:

- **All APIs** — agent can use any API in the store
- **Specific APIs** — limit to a whitelist of APIs
- **Auto-create** — agent can use APIs not yet added to your project (auto-provisions them)
- **Spending limit** — cap ZP usage per period (e.g., 1000 ZP per month)

## Pricing

Each tool call costs ZapPoints (1-50 ZP depending on the API). The free plan includes 1,000 ZP/month. See [zapifyapi.com/pricing](https://zapifyapi.com/#pricing) for plans.

## Links

- Website: https://zapifyapi.com
- Dashboard: https://zapifyapi.com/dashboard
- API Docs: https://zapifyapi.com/docs
- GitHub: https://github.com/TamirKashy/zapifyapi-mcp-server

## License

MIT