# Lolipop MCP Server

[日本語版 README はこちら / Japanese README](./README.ja.md)

The official remote [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [Lolipop Rental Server](https://lolipop.jp/) — a shared web hosting service operated by [GMO Pepabo, Inc.](https://pepabo.com/)

Manage domains, subdomains, free SSL certificates, and WordPress installations — all through natural language conversations with AI assistants.

## Endpoint

```
https://lolipop.jp/api/v1/mcp
```

Transport: Streamable HTTP. Authentication: Personal Access Token (PAT) via the `Authorization: Bearer` header.

## Features

- **Domain management** — add, list, update (public folder), and remove custom domains
- **Subdomain management** — add, list, and remove subdomains
- **SSL** — list free SSL certificates and request issuance (Let's Encrypt)
- **WordPress** — list installations and run a one-click install
- **Account info** — retrieve the authenticated API key's account information (plan, server, rate limit)

Pricing: **MCP server access is free.** A valid Lolipop Rental Server contract is required.

## Authentication

The Lolipop MCP server authenticates with a **Personal Access Token (PAT)**, issued from the Lolipop user panel.

1. Sign in to the [Lolipop user panel](https://user.lolipop.jp/) and issue an API key (PAT). Copy the token (`lp_pat_...`).
2. Register the endpoint URL **together with the `Authorization: Bearer <PAT>` header** in your MCP client (see Quick Start below).

Scopes are selected at issuance time (`domains:read` / `domains:write` / `ssl:read` / `ssl:write` / `wordpress:read` / `wordpress:write`). Requests exceeding the token's scope return `403 insufficient_scope`.

> **Note:** claude.ai (the web app's custom connectors) currently requires OAuth and cannot pass a static `Authorization` header, so it is not supported at this time. Use a client that supports custom headers (Claude Code, Cursor, Gemini CLI, OpenAI Codex), or the `mcp-remote` stdio bridge below.

## Quick Start

> **Keep your PAT out of committed files and shell history.** Store it in an environment variable (e.g. `LOLIPOP_PAT`) and reference it, rather than pasting the raw token into a config file or a command line. The examples below use `${LOLIPOP_PAT}`.

```bash
export LOLIPOP_PAT="lp_pat_..."   # your issued token
```

### Claude Code

```bash
claude mcp add --transport http lolipop https://lolipop.jp/api/v1/mcp \
  --header "Authorization: Bearer ${LOLIPOP_PAT}"
```

[Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp)

### Cursor

Add to `.cursor/mcp.json`. Cursor expands `${env:VAR}` references, so the raw token stays in your environment, not the file:

```json
{
  "mcpServers": {
    "lolipop": {
      "url": "https://lolipop.jp/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:LOLIPOP_PAT}"
      }
    }
  }
}
```

### Gemini CLI

Add to `~/.gemini/settings.json`. Gemini CLI expands `$VAR` / `${VAR}` references from the environment:

```json
{
  "mcpServers": {
    "lolipop": {
      "httpUrl": "https://lolipop.jp/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${LOLIPOP_PAT}"
      }
    }
  }
}
```

See the [Gemini CLI MCP server documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md) for details.

### OpenAI Codex CLI

Codex supports remote MCP servers and can read the token from an environment variable via `bearer_token_env_var`. Configure `https://lolipop.jp/api/v1/mcp` per the [Codex MCP documentation](https://developers.openai.com/codex/mcp):

```toml
[mcp_servers.lolipop]
url = "https://lolipop.jp/api/v1/mcp"
bearer_token_env_var = "LOLIPOP_PAT"
```

### Local stdio bridge (for clients without custom-header support)

Use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) to bridge a stdio-only client to the remote endpoint. Reference the token via environment variable so it does not appear in the config file:

```json
{
  "mcpServers": {
    "lolipop": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://lolipop.jp/api/v1/mcp",
        "--header", "Authorization: Bearer ${LOLIPOP_PAT}"
      ]
    }
  }
}
```

## Documentation

- [Official MCP server guide (Japanese)](https://lolipop.jp/developers/rentalserver/mcp/)
- [Public API reference (Japanese)](https://lolipop.jp/developers/rentalserver/api/)

## Requirements

- A [Lolipop Rental Server](https://lolipop.jp/) account on a supported plan
- A Personal Access Token (PAT) issued from the user panel
- An MCP-compatible client that supports custom request headers (Claude Code, Cursor, Gemini CLI, OpenAI Codex CLI, etc.)

## Support

- For service-related inquiries: [Lolipop Support](https://lolipop.jp/support/)
- For issues with this repository: please open a [GitHub Issue](https://github.com/pepabo/lolipop-mcp/issues)

## License

[MIT](./LICENSE)