@newfold/wp-mcp-connector

Connects stdio-based MCP clients (Claude Desktop, Cursor, etc.) to the WordPress MCP HTTP endpoint. It handles authentication (OAuth 2.1 with PKCE, JWT, application passwords, WooCommerce keys, custom headers), transport detection, session-id management, and optional system-proxy routing so multiple services can use a single, well-supported connector instead of bundling their own.

Distributed as a scoped npm package under Newfold Labs.

Installation

npm install @newfold/wp-mcp-connector

Or run on demand:

npx -y @newfold/wp-mcp-connector

Configure your MCP client

Add an entry to your MCP client configuration (shown here for Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": [ "-y", "@newfold/wp-mcp-connector" ],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com",
        "OAUTH_ENABLED": "true"
      }
    }
  }
}

The connector runs until the client disconnects. Re-opening the client will restart it automatically.

Authentication methods

Authentication methods are resolved in this priority order. The first one satisfied by the environment is used:

1. JWT — set JWT_TOKEN.
2. OAuth 2.1 — set OAUTH_ENABLED=true. Uses authorization-code flow with PKCE by default; set OAUTH_FLOW_TYPE=implicit for legacy sites.
3. WordPress application password / basic auth — set WP_API_USERNAME and WP_API_PASSWORD.
4. Custom headers only — when CUSTOM_HEADERS is the sole auth source (for API-key based setups), the connector forwards the headers with no Authorization header.

WooCommerce report tools (wc_reports_*) automatically use WOO_CUSTOMER_KEY / WOO_CUSTOMER_SECRET instead of the primary basic-auth credentials when those tools are invoked.

OAuth 2.1 behaviour

• PKCE (S256) is always on for the authorization-code flow.
• Protected-resource metadata (RFC 9728) is discovered first; the connector falls back to authorization-server metadata (RFC 8414) and, failing that, an unauthenticated probe to read the WWW-Authenticate header.
• Dynamic client registration (RFC 7591) runs automatically when no WP_OAUTH_CLIENT_ID is supplied and the authorization server advertises a registration endpoint.
• Resource indicators (RFC 8707) are included in the authorization and token requests unless OAUTH_RESOURCE_INDICATOR=false.
• Tokens are persisted under ~/.newfold/wp-mcp-connector/v<version>/ with file mode 0600 and isolated per site by an MD5 hash of the URL.
• Multiple connector instances coordinate via a lockfile so that only one opens a browser window at a time.

Environment variables

| Variable | Purpose | Default | | --- | --- | --- | | WP_API_URL | WordPress site URL (required) | — | | OAUTH_ENABLED | "true" to enable OAuth | false | | OAUTH_FLOW_TYPE | authorization_code or implicit | authorization_code | | OAUTH_USE_PKCE | Toggle PKCE (required for authorization_code) | true | | OAUTH_DYNAMIC_REGISTRATION | Allow dynamic client registration | true | | OAUTH_RESOURCE_INDICATOR | Send RFC 8707 resource indicator | true | | OAUTH_SCOPES | Comma-separated scopes | read,write | | OAUTH_CALLBACK_PORT | Loopback port for the redirect | auto | | OAUTH_HOST | Loopback host | 127.0.0.1 | | WP_OAUTH_CLIENT_ID | Pre-registered OAuth client id | — | | OAUTH_AUTHORIZE_ENDPOINT | Override authorize endpoint (legacy) | — | | OAUTH_TOKEN_ENDPOINT | Override token endpoint (legacy) | — | | JWT_TOKEN | JWT bearer token | — | | WP_API_USERNAME | WordPress username | — | | WP_API_PASSWORD | WordPress application password | — | | WOO_CUSTOMER_KEY | WooCommerce consumer key | — | | WOO_CUSTOMER_SECRET | WooCommerce consumer secret | — | | CUSTOM_HEADERS | Extra headers (JSON object or K:V,K:V) | — | | USE_SYSTEM_PROXY | Honour system PAC / SOCKS / HTTP proxies | false | | WP_MCP_CONFIG_DIR | Override credential storage root | ~/.newfold/wp-mcp-connector | | LOG_LEVEL | 0 error, 1 warn, 2 info, 3 debug | dev → 3, prod → 2 | | LOG_FILE | Append structured logs to a file | — | | LOG_TO_STDERR | "true" to also mirror logs to stderr | false |

Custom headers

{
  "env": {
    "WP_API_URL": "https://example.com",
    "CUSTOM_HEADERS": "{\"X-API-Key\": \"secret\"}"
  }
}

Or as a pair list: CUSTOM_HEADERS="X-API-Key:secret,X-Other:value".

Programmatic use

You can import the connector as a library (e.g. to embed it in another Node process rather than spawning it as a CLI):

import { startBridge, readSettings, logger } from "@newfold/wp-mcp-connector";

logger.info( `WP_API_URL = ${ readSettings().wpApiUrl }`, "host" );
await startBridge();

The library also exposes lower-level primitives — OAuth21Provider, sendWordPressRequest, detectTransport, createSessionContext, etc. — for callers that need to customise parts of the pipeline.

Development

npm install
npm run typecheck
npm test
npm run build

Releases are cut by running the Prepare Release workflow, which bumps the version and opens a PR. After merging the PR, tagging the merge commit (git tag vX.Y.Z && git push --tags) triggers the Publish NPM Package workflow.

Credential storage layout

<WP_MCP_CONFIG_DIR>/v<version>/
  <server-id>_tokens.json        OAuth tokens (mode 0600)
  <server-id>_client.json        Registered OAuth client (mode 0600)
  <server-id>_pkce_verifier.txt  PKCE verifier (transient, mode 0600)
  <server-id>_oauth_state.txt    OAuth state parameter (transient)
  <server-id>_auth.lock          Cross-process coordination lockfile

<server-id> is an MD5 hash of the site URL; this isolates credentials per WordPress install without exposing the URL in filenames.

License

GPL-3.0