# CustomJS MCP Server

> A remote [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI agents web superpowers — **host HTML pages on a public URL, generate PDFs, capture screenshots, scrape sites, and run sandboxed code** — using your own [CustomJS](https://www.customjs.space) API key.

| | |
|---|---|
| **Endpoint** | `https://mcp.customjs.space/customjs/mcp` |
| **Transport** | Streamable HTTP |
| **Auth** | `x-customjs-api-key` header (per-user API key) |

There's nothing to install or self-host — it's a hosted remote MCP server. Bring your CustomJS API key and connect.

## Tools

| Tool | What it does |
|------|--------------|
| `customjs_host_html_page` | Publish static HTML and get a public `lp.customjs.space` URL (upsert by name) |
| `customjs_list_html_pages` | List your hosted pages (name, url, pageId) |
| `customjs_delete_html_page` | Delete a hosted page by name or pageId |
| `customjs_html_to_pdf` | Convert HTML to PDF (Nunjucks templating) |
| `customjs_markdown_to_pdf` | Convert Markdown to PDF |
| `customjs_screenshot` | Capture a full-page website screenshot |
| `customjs_scrape_html` | Extract fully-rendered HTML (JavaScript-aware) |
| `customjs_run_code` | Run JavaScript in a secure sandbox |
| `customjs_help` | Built-in usage examples (topics: pages, pdf, screenshot, scraping, code) |

## Get an API key

Create a free key at <https://www.customjs.space/integration/native-api/api-key>. Your key is sent per request as the `x-customjs-api-key` header and is never stored by the connector.

## Connect

### Claude Code — plugin (recommended)

```text
/plugin marketplace add customjs/claude-plugin
/plugin install customjs@customjs-tools
```

You'll be prompted only for your API key. (See [customjs/claude-plugin](https://github.com/customjs/claude-plugin).)

### Claude Code — without the plugin

```bash
claude mcp add --transport http \
  --header "x-customjs-api-key: <your-key>" \
  customjs https://mcp.customjs.space/customjs/mcp
```

### Claude Desktop (JSON config via `mcp-remote`)

```json
{
  "mcpServers": {
    "customjs": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.customjs.space/customjs/mcp",
        "--header", "x-customjs-api-key:${CUSTOMJS_API_KEY}"
      ],
      "env": { "CUSTOMJS_API_KEY": "your-key" }
    }
  }
}
```

### Other MCP clients (Cursor, VS Code, etc.)

Add a **remote / HTTP** MCP server pointing at `https://mcp.customjs.space/customjs/mcp` with the header `x-customjs-api-key: <your-key>`.

## Hosting HTML pages

`customjs_host_html_page` publishes static HTML and returns a public `https://lp.customjs.space/<shortId>` URL. Hosting again with the same `name` **updates** the existing page (upsert by name).

> Note: the public URL is served via CloudFront, so immediately after an update it may briefly show the previous content until the cache refreshes.

## Official MCP Registry

This server is published to the [official MCP Registry](https://registry.modelcontextprotocol.io) as **`space.customjs/customjs-mcp`** (DNS-verified on `customjs.space`) — see [`server.json`](./server.json). For how it's published and the full directory list, see [PUBLISHING.md](./PUBLISHING.md).

## Links

- Website — <https://www.customjs.space>
- Get an API key — <https://www.customjs.space/integration/native-api/api-key>
- Claude Code plugin — <https://github.com/customjs/claude-plugin>
- MCP protocol — <https://modelcontextprotocol.io>

## License

The contents of this repository (documentation and registry manifest) are released under the [MIT License](./LICENSE). The CustomJS service itself requires a valid API key and is governed by CustomJS's terms of service at <https://www.customjs.space>.