mcp

<p align="center">
  <img src="assets/logo.svg" alt="PocketBase Cloud" width="96" height="96">
</p>

<h1 align="center">PocketBase Cloud MCP Server</h1>

<p align="center">
  <b>The official Model Context Protocol (MCP) server for PocketBase Cloud: a hosted bridge that lets your AI assistant work in your PocketBase Cloud account — projects, PocketBase instances, frontends and backends, deploys and logs, custom domains, and the collections and records inside each instance.</b>
</p>

<p align="center">
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/Model_Context_Protocol-compatible-000000?logo=modelcontextprotocol&logoColor=white" alt="Model Context Protocol compatible"></a>
  <a href="server.json"><img src="https://img.shields.io/badge/MCP_Registry-com.pocketbasecloud-000000?logo=modelcontextprotocol&logoColor=white" alt="MCP Registry: com.pocketbasecloud"></a>
  <a href="#how-it-works"><img src="https://img.shields.io/badge/Auth-OAuth_2.1%20%7C%20CLI%20token-2EBC4F" alt="Auth: OAuth 2.1 or CLI token"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-F04E23" alt="License: Apache 2.0"></a>
</p>

<p align="center">
  <a href="https://mcp.pocketbasecloud.com/"><b>Connect page</b></a> ·
  <a href="#tools"><b>Tools</b></a> ·
  <a href="#data-and-security"><b>Data and security</b></a> ·
  <a href="https://pocketbasecloud.com"><b>PocketBase Cloud</b></a>
</p>

---

**PocketBase Cloud** hosts PocketBase backends, frontends and server apps. Connect your account once, then ask your
assistant in plain words; it picks and runs the right actions.

With the PocketBase Cloud MCP Server, your assistant can:

* **See what is running:** projects, PocketBase instances, frontends and backends with their status, recent
  deploys, and the logs of instances and backends.
* **Find out why something broke:** read a failed deploy's build log and explain the fix.
* **Start an app:** create projects and PocketBase instances in the region you choose.
* **Ship:** add and verify custom domains, deploy hooks and static sites, and get the exact `pbc` command to deploy
  your source code.
* **Work with data:** design collections and API rules, and read, create, update and delete records.
* **Harden an instance:** review API rules for security gaps, find slow requests, and back up before risky
  changes.

> [!IMPORTANT]
> **You choose the access when you connect:** read and write or read only, and all projects or a single one.
> [Options](#options) in the server URL can narrow a connection, never widen it. Deleting needs your explicit
> approval of that exact change.

## One-click setup

Pick your AI client below. Each button uses your client's native install link, so you don't need to edit any JSON
config by hand.

<table align="center">
  <tr>
    <td align="center" width="200">
      <a href="https://cursor.com/en/install-mcp?name=pocketbasecloud&config=eyJ1cmwiOiJodHRwczovL21jcC5wb2NrZXRiYXNlY2xvdWQuY29tL21jcCJ9">
        <img src="https://img.shields.io/badge/Cursor-000000?style=for-the-badge&logo=cursor&logoColor=white" alt="Add to Cursor"><br>
        <b>Add to Cursor</b>
      </a>
      <br><sub>Build on PocketBase from your editor.</sub>
    </td>
    <td align="center" width="200">
      <a href="https://vscode.dev/redirect/mcp/install?name=pocketbasecloud&config=%7B%22url%22%3A%22https%3A%2F%2Fmcp.pocketbasecloud.com%2Fmcp%22%2C%22type%22%3A%22http%22%7D">
        <img src="https://img.shields.io/badge/VS_Code-0098FF?style=for-the-badge&logoColor=white" alt="Add to VS Code"><br>
        <b>Add to VS Code</b>
      </a>
      <br><sub>Use it from GitHub Copilot.</sub>
    </td>
    <td align="center" width="200">
      <a href="#claude-and-chatgpt">
        <img src="https://img.shields.io/badge/Claude-D97757?style=for-the-badge&logo=claude&logoColor=white" alt="Add to Claude"><br>
        <b>Add to Claude</b>
      </a>
      <br><sub>Add it as a custom connector.</sub>
    </td>
    <td align="center" width="200">
      <a href="#claude-and-chatgpt">
        <img src="https://img.shields.io/badge/ChatGPT-10A37F?style=for-the-badge&logoColor=white" alt="Add to ChatGPT"><br>
        <b>Add to ChatGPT</b>
      </a>
      <br><sub>Add it as a custom MCP server.</sub>
    </td>
  </tr>
</table>

The server URL, for any other client:

```
https://mcp.pocketbasecloud.com/mcp
```

Paste it exactly: the address ends in `/mcp`.

### Let your agent do the setup

Most AI coding agents can add the server and start sign-in themselves. Paste this into your agent:

```
Add the PocketBase Cloud MCP server https://mcp.pocketbasecloud.com/mcp to this agent
(remote, Streamable HTTP, OAuth), following https://mcp.pocketbasecloud.com/.
Then start the authentication flow so I can sign in to PocketBase Cloud.
```

### Claude and ChatGPT

**Claude (claude.ai and Claude Desktop)**

1. **Customize → Connectors**, then **+ Add → Add custom connector**.
2. Name it (for example *PocketBase Cloud*), paste the server URL, and continue. If asked how Claude identifies
   itself, choose **Register automatically**. Click **Add**.
3. Click **Connect**, sign in to PocketBase Cloud, then choose the access and the project.

On a Team or Enterprise plan, an owner adds it once under **Organization settings → Connectors → Add → Custom →
Web**; then each member clicks **Connect**.

**ChatGPT**

1. **Plugins → + → Add custom MCP server.**
2. Name it, enter the server URL under **Connection** with **OAuth** authentication, accept the warning about
   custom servers, then **Create as a plugin**.
3. Install the plugin, sign in to PocketBase Cloud when ChatGPT asks, then type `@` in a chat to use it.

### Other clients

| Client | Command or configuration |
| --- | --- |
| Claude Code | `claude mcp add --transport http pocketbasecloud https://mcp.pocketbasecloud.com/mcp`, then run `/mcp` in a session to sign in |
| Claude Code (plugin, with skills) | `/plugin marketplace add pocketbasecloud/mcp`, then `/plugin install pocketbase-cloud@pocketbase-cloud` |
| Codex | `codex mcp add pocketbasecloud --url https://mcp.pocketbasecloud.com/mcp`, then `codex mcp login pocketbasecloud` |
| Cursor | The **Add to Cursor** button above, or `"pocketbasecloud": { "url": "https://mcp.pocketbasecloud.com/mcp" }` under `mcpServers` in `.cursor/mcp.json` |
| VS Code / GitHub Copilot | The **Add to VS Code** button above, or `"pocketbasecloud": { "type": "http", "url": "https://mcp.pocketbasecloud.com/mcp" }` under `servers` in `.vscode/mcp.json` |
| Devin Desktop (formerly Windsurf) | In the Cascade panel, **… → Open MCP config file**, and add `"pocketbasecloud": { "url": "https://mcp.pocketbasecloud.com/mcp" }` under `mcpServers`. For the Devin agent: `devin mcp add pocketbasecloud https://mcp.pocketbasecloud.com/mcp`, then `devin mcp login pocketbasecloud` |
| Gemini CLI | `gemini extensions install https://github.com/pocketbasecloud/mcp`, then `/mcp auth pocketbasecloud` |
| Any other MCP client | The server URL, with the Streamable HTTP transport and OAuth |

**Scripts and CI:** instead of signing in, send a PocketBase Cloud CLI access token (portal → Account → CLI access
token) as `Authorization: Bearer <token>`. See [How it works](#how-it-works).

## Contents

* [One-click setup](#one-click-setup)
* [Plugin packaging and compatibility](#plugin-packaging-and-compatibility)
* [Tools](#tools)
* [Options](#options)
* [Before you start](#before-you-start)
* [Data and security](#data-and-security)
* [How it works](#how-it-works)
* [Example prompts](#example-prompts)
* [Skills](#skills)
* [Troubleshooting](#troubleshooting)
* [Security](#security)
* [Support and feedback](#support-and-feedback)
* [Disclaimer](#disclaimer)

---

## Plugin packaging and compatibility

This repository publishes the same MCP server and skills in several package formats, so each client can use its
native discovery and installation flow:

| Format | Manifest and configuration | Shared components |
| --- | --- | --- |
| [Agent Plugins v1](https://agent-plugins.org/) | [`plugin.json`](plugin.json) and [`mcp.json`](mcp.json) | [`skills/`](skills/) |
| Claude Code plugin | [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) and [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) | [`.mcp.json`](.mcp.json) and [`skills/`](skills/) |
| Cursor plugin | [`.cursor-plugin/plugin.json`](.cursor-plugin/plugin.json) | [`.mcp.json`](.mcp.json) and [`skills/`](skills/) |
| Gemini CLI extension | [`gemini-extension.json`](gemini-extension.json) | MCP server configuration embedded in the manifest |
| MCP Registry | [`server.json`](server.json) | Remote server metadata |

Both `mcp.json` and `.mcp.json` are intentional: Agent Plugins requires the root `mcp.json` and its portable
transport vocabulary (`streamable-http`), while Claude Code and Cursor read `.mcp.json` with theirs (`http`). Gemini
CLI names the Streamable HTTP endpoint `httpUrl`. Keep the endpoint the same in all of them; `npm run validate`
checks it.

## Tools

The server groups its tools. Groups marked *opt-in* are added with the [`features`](#options) option. The live
list, with every tool, is on the [connect page](https://mcp.pocketbasecloud.com/).

| Group | Default | What it covers |
| --- | :---: | --- |
| `account` | ✅ | Overview of the account, plan and Free trial, projects, regions; create a project. |
| `resources` | ✅ | PocketBase instances, frontends and backends: list, inspect, create an instance, runtime settings, continuous backup. |
| `deploy` | ✅ | Deploys and their build logs, runtime logs, a one-call diagnosis, hooks, static sites, and the `pbc` command to deploy source code. |
| `domains` | ✅ | Add, verify, check and remove custom domains. |
| `docs` | ✅ | Search the PocketBase and PocketBase Cloud guide for agents. |
| `database` | ✅ | Inside an instance: collections, API rules, records, request logs, backups, crons, security and performance checks, TypeScript ty