# pagerankcafe-mcp

**The marketing platform for your AI agents.**

An MCP (Model Context Protocol) server for the [PageRankCafe](https://pagerankcafe.com) API. It gives an AI agent tools to read and post link ads, banner ads, YouTube video ads, and press releases/blog articles on PageRankCafe, check credit and referral balances, read per-placement performance, and (on paid tiers) pull platform-wide ad performance insights.

## Getting a key

1. Create a PageRankCafe account at <https://pagerankcafe.com>.
2. Upgrade to a paid membership (Bronze/Silver/Gold) at <https://pagerankcafe.com/membership-info> if you want to use the write and insights tools. Read tools work on a free account too.
3. Generate an API key at <https://pagerankcafe.com/apiKeys>.

Account creation and key generation are both manual, human steps on the website — there is no programmatic signup.

## Configuration

The server reads its configuration from environment variables:

| Variable | Required | Default | Description |
|---|---|---|---|
| `PAGERANKCAFE_API_KEY` | Yes | — | Your API key from `/apiKeys`. The server exits immediately with an error if this is not set. |
| `PAGERANKCAFE_BASE_URL` | No | `https://pagerankcafe.com` | API base URL. Override only for testing against a non-production environment. |

## Install

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pagerankcafe": {
      "command": "npx",
      "args": ["-y", "pagerankcafe-mcp"],
      "env": {
        "PAGERANKCAFE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add pagerankcafe --env PAGERANKCAFE_API_KEY=your-api-key-here -- npx -y pagerankcafe-mcp
```

### Cursor

Add to your Cursor MCP settings (`~/.cursor/mcp.json` or the project's `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "pagerankcafe": {
      "command": "npx",
      "args": ["-y", "pagerankcafe-mcp"],
      "env": {
        "PAGERANKCAFE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Tools

Every write tool and the insights tool require a paid membership (Bronze/Silver/Gold); the API returns an error for free accounts. Read tools work on any valid key, including free accounts.

| Tool | Membership | Description |
|---|---|---|
| `health` | Free | Checks API connectivity and returns the authenticated user's username and membership status. |
| `list_links` | Free | Lists your active link ads. |
| `list_banners` | Free | Lists your active banner ads. |
| `list_youtube_ads` | Free | Lists your active YouTube video ads. |
| `list_press_releases` | Free | Lists your active press releases / blog articles. |
| `get_credits` | Free | Returns your credit balance, available post slots, links viewed, and links remaining. |
| `get_referral_stats` | Free | Returns your referral counts (today, 7 day, 30 day, all time). |
| `list_posts` | Free | Returns per-placement performance for link, banner, YouTube, or press-release ads. |
| `upload_image` | Paid | Uploads an image (local file path or base64) and returns a hosted HTTPS URL. |
| `create_banner` | Paid | Creates a new banner ad. |
| `post_banner` | Paid | Posts an existing banner into rotation using credits. |
| `create_youtube_ad` | Paid | Creates a new YouTube video ad. |
| `update_youtube_ad` | Paid | Partially updates an existing YouTube ad you own. |
| `create_press_release` | Paid | Creates a new press release / blog article. |
| `update_press_release` | Paid | Partially updates an existing press release you own. |
| `post_press_release` | Paid | Posts an existing press release to the home-page widget using credits. |
| `create_link` | Paid | Creates a new link ad. |
| `post_link` | Paid | Posts an existing link ad into rotation using credits (free/credit posts only: `ad_days` must be 0; `view_time`/`view_credits` are derived server-side from `icon`/`bold`/`double_time`, not accepted as input). Returns `status: "active"` when the post goes live immediately, or `status: "pending"` (with an explanatory `message`) when the posting user needs approval first. |
| `get_platform_insights` | Paid | Trailing-30-day platform performance aggregates by ad type and option, plus current prices. |

Full request/response detail for each underlying endpoint is in the OpenAPI spec at <https://pagerankcafe.com/api/spec> (rendered at <https://pagerankcafe.com/api/docs>).

## Error handling

Every tool returns the API's JSON response as the tool result on success. On a non-2xx API response, the tool returns an MCP tool error (`isError: true`) carrying the API's error message. There are no retries and no silent fallbacks — a failed call always surfaces as a failed tool call.

## Development

```bash
npm install
npm run build   # compiles src/ to dist/ with tsc
npm test        # builds, then runs the stdio smoke test (no network required)
```

The test starts the built server as a subprocess over stdio (using `StdioClientTransport` from `@modelcontextprotocol/sdk`), lists its tools, and checks the full tool list is present — no real API key or network access is used.