=== GripMCP ===
Contributors: akshay89
Tags: mcp, ai, claude, model context protocol, assistant
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect Claude and other AI assistants to WordPress over MCP. Every action runs as a real WordPress user, with that user's permissions.

== Description ==

GripMCP turns your WordPress site into a Model Context Protocol (MCP) server. Paste one address into your AI assistant, approve the connection, and the assistant can manage your site in plain language: write and edit posts, upload images, organise categories and menus, moderate comments, look into errors, and more. Paid plans add plugin and theme management, WooCommerce, page builders and developer tools.

The assistant never gets more power than the person who connected it. Every action is checked against that WordPress user's real role and capabilities, deletions wait for your approval unless you choose otherwise, and the riskiest features are off until you switch them on.

= Connect in a minute =

* **One address.** Your site answers at `https://your-site.com/mcp`.
* **One-click connect.** In Claude, add a custom connector, paste the address, sign in to WordPress and approve. No tokens or config files. This uses the standard MCP authorization flow (OAuth 2.1 with PKCE and dynamic client registration), so other MCP clients that support it connect the same way.
* **Access tokens** for config-file clients such as Claude Desktop or `mcp-remote`. Make as many as you need: tokens are stored hashed, expire after 90 days unless you choose otherwise, work only at the GripMCP endpoint, and can be revoked at any time. WordPress Application Passwords work too.
* **You choose who can connect.** Administrators always can; other roles only when you allow them.

= What your assistant can do with the free plugin =

* **Content:** list, read, create, update, edit in place and delete posts, pages and custom post types; categories, tags and custom taxonomies; menus; comments; custom fields; settings; revisions and restore; the theme's Additional CSS.
* **Media:** upload from a link or a file in the chat, place images into a post or set them as the featured image. On assistants that support in-chat panels, you can drag images onto an upload panel right in the conversation.
* **Users:** list, create and update users, and remove them with their content handed to someone else.
* **Safety:** deletions held for your approval, with a check of what they would break; revisions to undo an edit.
* **Site health:** site health checks, the PHP error log, temporary debug logging that switches itself off, a record of recent crashes, cron events, cache flushing (including Elementor and page-cache plugins such as LiteSpeed Cache and WP Rocket), and a check of how any page renders.
* **Plugin abilities:** on WordPress 6.9 and later, discover and run the actions other plugins publish through the WordPress Abilities API.
* **Progress cards:** for requests that take several steps, one live card in the chat with each step and the outcome.

= With a paid plan =

GripMCP Creator, Operator and Fleet are a separate download, sold with a monthly or yearly licence at [gripmcp.com](https://gripmcp.com/pricing/). Each plan includes everything in the plans before it.

* **Creator:** search, install, activate, update, roll back and remove plugins and themes.
* **Operator:** WooCommerce orders, refunds, products, stock, customers, coupons and sales reports; Elementor, WPBakery and Divi 4 layouts read and edited element by element, saved through the builder's own save and with a restore point for every change; WP-CLI commands through a built-in emulator that needs no shell; read-only SQL queries; raw REST API requests; and the full audit log, with 90 days of history, filters and CSV export.
* **Fleet:** theme and plugin file editing with syntax and run-time checks and a backup before every change; theme drafts you preview before they go live; new block themes; and a serialization-safe database search and replace for moving a site to a new address.

WooCommerce, page-builder and Abilities tools appear only on sites that have those features. If you activate one of those plugins, or move to a higher plan, after connecting, reconnect GripMCP in your AI app to load the new tools; GripMCP tells the assistant.

= Safe by default =

* The endpoint is off until you switch it on, and it requires HTTPS.
* Every tool checks the connected user's WordPress capabilities. GripMCP never grants a capability the user does not already have.
* Access keys work only on the GripMCP endpoint, not on the rest of the WordPress API.
* Destructive actions (deleting content, users, plugins or themes, refunding or cancelling an order, and changing who has admin-level access: making someone an administrator or shop manager, or changing such an account's email or password) are set to "Ask me first" on a new install: each one waits for you to approve it on a page in your own WordPress admin. Requests waiting for you are also listed on the Approvals tab of the GripMCP screen, with a count on its menu item, so a lost link never strands one. There is no way for an assistant to approve its own request. Under Permissions you can switch them off entirely, or allow them without asking.
* Before a destructive action is put up for approval, GripMCP checks what it would break: a plugin's shortcodes, blocks or widgets used on your pages, other plugins that require it, a page that is your homepage or in a menu, an image used as the logo or a featured image, a user who is the last administrator. You see the findings with the request; high-risk ones recommend trying it on a staging copy first and ask you to confirm before it runs.
* In the paid plans, editing theme and plugin files, installing packages and REST writes are each off until you switch them on. WP-CLI commands run in PHP and never open a shell. File writes are confined to themes, plugins and uploads, syntax-checked before saving, and an existing file is backed up before it is changed or deleted. A PHP change to the active theme or an active plugin is checked by loading the site, and undone if it causes a fatal error.
* Credentials are protected: secret-looking options are refused, passwords and API keys inside other plugins' settings (a payment gateway's secret key, an SMTP password) are shown to the assistant as "[redacted]" and kept when a setting is saved back, password and key columns are redacted from SQL results, and a user can never be given a role with more power than yours.
* A per-user rate limit, an activity log of every tool call, and a connection diagnostics log for when a connector stops working.

= In-chat progress cards =

For requests that take several steps, assistants that support in-chat panels (the MCP Apps standard) show one live card with each step and its result, then the outcome. An assistant that declares the extensions it supports when it connects, and leaves panels out of them, is not sent the card tools at all. Developers can switch off the upload panel with the `gripmcp/in_chat_uploads` filter, and the cards with the `gripmcp/progress_cards` filter.

= External services =

GripMCP has no analytics of its own and no phone-home. It contacts another server only when you or your assistant ask for something that needs it:

* **Freemius** (api.freemius.com), the service that sells and licenses the paid plans. After activation GripMCP asks whether you want to opt in; only if you do, or when you start a purchase, a trial or a licence activation, does it send Freemius your site's address, your WordPress, PHP and GripMCP versions, and the email you opt in with. After that, while you stay opted in or have a licence active on the site, it checks in with Freemius once a day to keep your licence and updates current. Skip it and nothing is sent. See the [Freemius privacy policy](https://freemius.com/privacy/) and [terms](https://freemius.com/terms/).
* **WordPress.org** (api.wordpress.org and downloads.wordpress.org), through WordPress's own update check and plugin and theme APIs: the site health check asks for pending updates with the same request WordPress itself sends from the Dashboard and Updates screens, and the paid plans search, install and update plugins and themes. See the [WordPress.org privacy policy](https://wordpress.org/about/privacy/).
* **A web address you or your assistant supply**, to download a file into the Media Library.
* **Your own site**, to fetch a page for the page-render check.

== Installation ==

1. Upload the `gripmcp` folder to `/wp-content/plugins/`, or go to Plugins → Add New → Upload Plugin and choose the zip.
2. Activate GripMCP.
3. Open **GripMCP** in the admin menu and switch the endpoint on with the switch at the top right. It saves as soon as you change it.
4. Copy the endpoint address from the **Setup** tab.
5. Connect your assistant:
	* **Claude (web, desktop or mobile):** Settings → Connectors → Add custom connector, paste the address, then sign in to WordPress and approve.
	* **Config-file clients:** create a token under **Access** and use it as `Authorization: Bearer <token>`.
6. Choose what the assistant may do under **Permissions**.

The short `/mcp` address needs pretty permalinks (Settings → Permalinks set to anything but "Plain"). Without them the Setup tab shows the longer REST address instead, ending in `?rest_route=/gripmcp/v1/rpc`, which works with any permalink setting.

== Frequently Asked Questions ==

= Which assistants work with GripMCP? =

Any MCP client that supports the Streamable HTTP transport. Claude connects with one click through a custom connector. Clients that read a config file connect with an access token.

= Is it safe? =

Every tool call runs as a WordPress user and is checked against that user's capabilities, exactly as wp-admin would check them. For the tightest control, connect as a dedicated user with a limited role, and keep "Destructive actions" on "Ask me first" (the default) or set it to "Off".

= Does it send my data anywhere? =

Not unless you choose to. GripMCP has no analytics of its own. The only outside servers it contacts are listed under "External services" above: Freemius only if you opt in or buy a plan, the others only when your assistant asks for that action.

= What is in the free plugin, and what do the paid plans add? =

The free plugin (the Explorer plan) covers everyday site care: content, media, users, categories, menus, comments, custom fields, settings, revisions, approvals for deletes, the debug log, site health and plugin abilities. No plan limits access tokens or connected apps. Creator adds plugin and theme management; Operator adds WooCommerce, Elementor, WPBakery and Divi, WP-CLI, read-only SQL, raw REST requests and the full audit log; Fleet adds theme and plugin file editing, theme drafts and database search and replace. Each paid licence covers a set number of sites.

= How do I move from a paid plan back to the free plugin? =

You don't have to: when a licence ends, the paid version keeps running with the free plugin's features. To switch to this free plugin, for its updates from WordPress.org, install and activate it first (if WordPress offers to replace the copy you have, accept), and only then delete the paid copy if it is still listed. Your settings, connected apps and activity log carry over. Deleting GripMCP while no other copy is installed removes all of them, and your assistant then has to connect again; your site's content is never touched.

= What does it store on my site? =

Its settings, hashed access tokens, OAuth clients and tokens, an activity log of tool calls (time, tool, user, result, duration and IP address: kept 3 days on the free plan, 7 on Creator and 90 on Operator and Fleet, and up to 30 days longer after a licence lapses), a connection log, file backups, page-builder restore points, and a short list of recent PHP fatal errors. Deleting the plugin from the Plugins screen removes all of it. Themes your assistant created are left in place, like any other theme.

= Does it require HTTPS? =

Yes, by default. On a site that is not served over HTTPS, the Setup tab shows a "Require HTTPS" switch you can turn off for testing, but tokens sent over plain HTTP can be intercepted.

= One-click connect does not work. What should I check? =

Open **GripMCP → Activity → Connection diagnostics**. It lists every token issued and every refused request with the reason. One-click connect needs HTTPS and a site at the root of its domain, because the discovery documents must sit at `/.well-known/`. If a security plugin blocks `.well-known` paths, allow them. Sites in a subdirectory can connect with an access token instead.

= My host strips the Authorization header. =

Some Apache and LiteSpeed setups drop it before PHP sees it, and then every app is refused. When you open the GripMCP screen, your browser sends the site a test request with the header, the way WordPress's own Site Health checks it, and the Setup tab warns you if it does not get through. To fix it, add this to the very top of `.htaccess`:

`RewriteEngine On`
`RewriteCond %{HTTP:Authorization} ^(.*)`
`RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]`

= My site already uses the /mcp address. =

Change GripMCP's short address by adding `define( 'GRIPMCP_SHORT_PATH', 'ai' );` to `wp-config.php` (any single word works), or set it to an empty string to turn the short address off and use the longer REST address. Then copy the new address from the Setup tab into your assistant.

= What does temporary debug logging change? =

Nothing, until your assistant switches it on to look into a problem. It then records PHP errors to a private file in `wp-content/gripmcp-logs` for the time it asked for (5 minutes to 24 hours) and switches itself off. It changes no PHP setting and never shows errors to visitors. To stop assistants switching it on, turn off "Let the assistant switch on debug logging" under More settings on the Permissions tab.

= How do I report a problem? =

Open **GripMCP → Activity → Report a problem** and describe what you were trying to do and what happened. GripMCP writes a post around your description and adds what is needed to look into it: your WordPress, PHP and plugin versions, your GripMCP settings, what it noticed in its own logs, and the error lines from your site's PHP error logs.

With the free plugin, support is on the [GripMCP forum](https://wordpress.org/support/plugin/gripmcp/) here on WordPress.org: click **Copy post**, then **Open the forum**, and paste it into a new topic with the title shown above it. Forum posts are public, so read it first and remove anything you would rather keep private; GripMCP leaves your site address out of it. On a paid plan, GripMCP writes an email instead: click **Copy email**, paste it into a new email to support@gripmcp.com with the subject shown above it, and send it, or download it as a file and attach it.

Settings that stop every app from connecting, such as a switched-off endpoint, are shown on the GripMCP screen next to their fix, so you may not need to write in at all. The report is written to leave out passwords, tokens, email and IP addresses, phone numbers, server folder names and your content, but read it before you send it. The plugin never sends it: only you do.

= Can I add my own tools? =

Yes. Register a class that extends `GripMCP\Tools\Abstract_Tool` through the `gripmcp/tools` filter. It is permission-checked, logged and listed to assistants automatically. The class gives the tool's name, title, description, input schema and group, the capability a user needs to call it, and a `run()` method that does the work.

= Which versions of WordPress and PHP does it support? =

WordPress 6.2 or later, tested up to 7.1. PHP 7.4 or later, tested up to 8.5.

== Changelog ==

= 1.0.0 =
* Initial release.
