How to Set Up Claude Code for a WordPress Project: The Full Configuration Guide

Cursor lives in your editor. Claude Code lives in your terminal. That sounds like a small distinction until you realize what it unlocks: an AI that can run wp plugin list, inspect your database, run your test suite, watch the output, and respond to what it sees — all without you touching the keyboard.

For day-to-day WordPress edits, Cursor is faster. For multi-file refactors, codebase audits, plugin modernization, or anything where the AI benefits from being able to do things (not just read and write code), Claude Code is the better tool.

This guide walks through the full setup: installing Claude Code, configuring CLAUDE.md for WordPress, connecting WP-CLI as a tool, MCP integrations, custom slash commands, and the workflows that make a terminal-based agent worth the context-switch from your editor.

Prerequisites: A WordPress project (local development environment recommended), WP-CLI installed and working, an Anthropic API key or Claude subscription with Claude Code access, and basic terminal comfort.

Step 1: Install Claude Code

Install Claude Code from the official Anthropic install method (typically via npm or a curl install script — check claude.com or Anthropic’s documentation for the current command, since the install path has changed a few times).

After install, run:

claude --version

You should see a version number. If the command isn’t found, your shell’s PATH doesn’t include the install location — check the install output for instructions.

Authenticate by running claude in any directory and following the prompts. Claude Code supports both Anthropic API keys (pay-per-use) and Claude subscription accounts (Pro, Max, Team). For consistent WordPress work, the subscription plans are usually better value than API usage; for occasional use, API works fine.

Step 2: Open your WordPress project and create `CLAUDE.md`

Navigate to your WordPress project root in the terminal:

cd ~/projects/my-wordpress-site

Just like Cursor reads .cursorrules, Claude Code reads CLAUDE.md at the project root on every session. Create one:

touch CLAUDE.md

Open it in your editor and paste this:

# Project context

This is a WordPress project. All code you generate or modify must follow
WordPress coding standards and security best practices.

## Project specifics

- WordPress version: [e.g. 6.5+]
- PHP version: [e.g. 8.2]
- Theme: [your theme name, or "custom"]
- Active plugins of note: [WooCommerce, ACF, etc.]
- Local environment: [LocalWP / wp-env / Docker / DDEV]
- Database access: WP-CLI is configured and available

## Security requirements (non-negotiable)

- Escape all output: esc_html(), esc_attr(), esc_url(), esc_js(), wp_kses().
- Sanitize all input: sanitize_text_field(), sanitize_email(), etc.
- All forms require wp_nonce_field() and verification with check_admin_referer().
- All AJAX handlers must verify nonces with check_ajax_referer().
- All privileged operations check capabilities with current_user_can().
- All database queries use $wpdb->prepare() — never concatenate user input.
- No deprecated functions: mysql_*, create_function, ereg, eregi.

## WordPress conventions

- Translation: __(), _e(), esc_html__(), esc_html_e() — always with text domain.
- Hooks: only use hooks that exist in core or active plugins. Never invent hook names.
- Distinguish actions (no return) from filters (must return first argument).
- HTTP requests: wp_remote_get / wp_remote_post, not cURL or file_get_contents.
- File operations in plugins: use WP_Filesystem, not direct PHP file functions.
- Database changes in plugins: dbDelta() in activation hooks, not raw CREATE TABLE.

## Workflow expectations

- Before making non-trivial changes, briefly explain what you plan to do
  and which files you'll touch. Wait for confirmation.
- After making changes, run any relevant tests or validation
  (php -l on changed PHP files, npm run build if JS changed).
- For destructive operations (deleting files, dropping tables, mass updates),
  always ask first.
- Use WP-CLI to inspect the live install when relevant. Don't guess
  about plugin activation status, post counts, option values, etc.

## Coding style

- WordPress PHP standards: snake_case functions/variables, PascalCase classes.
- Tabs for PHP indentation, 2 spaces for JS/CSS.
- Docblocks on all functions and classes (@param, @return, @since).
- Namespaces for plugin classes (PSR-4 autoloading preferred).

## Project notes

[Anything weird, undocumented, or important about this codebase.
Architectural decisions, "why we did it this way" history,
known fragile areas, third-party API quirks, etc.]

The “Project notes” section is the one that pays off most over time. As you work, when you discover something non-obvious — a custom field that breaks if you sanitize it the normal way, a plugin conflict, an API rate limit — add it. Future Claude Code sessions inherit that knowledge automatically.

Test that Claude Code is reading it. Start a session:

claude

Then ask: “What’s in CLAUDE.md? Summarize the project context.”

Claude Code should summarize the contents accurately. If it doesn’t reference the file, the file isn’t being picked up — check the filename (exactly CLAUDE.md, case sensitive on most filesystems) and that it’s at the directory where you started Claude Code.

Step 3: Configure WP-CLI as a tool

This is the step that makes Claude Code substantively more useful than Cursor for WordPress work. Once Claude can run WP-CLI commands, it can:

Check which plugins are active and their versions
Inspect post counts, user counts, options, transients
Run database queries via wp db query
Activate, deactivate, install, and update plugins
Reset passwords, manage users
Export and import content
Run cron events manually
Check site health

The good news: Claude Code can run shell commands by default, and WP-CLI is just a shell command. There’s no special integration needed — you only need to tell Claude Code in CLAUDE.md that WP-CLI is available (which the template above does).

Confirm WP-CLI works in your project directory:

wp plugin list

If you see your plugin list, you’re set. If you get “Error: This does not seem to be a WordPress installation,” check that you’re in the WordPress root and that wp-config.php is accessible. For some local environments (Docker-based setups, especially), WP-CLI needs to be configured to talk to the right container — check your stack’s docs.

Test it through Claude Code. Start a session in your project root and ask:

“How many published posts are in this WordPress install? Use WP-CLI.”

Claude should run something like wp post list --post_status=publish --format=count and return the actual number. If it tries to guess instead of running the command, your CLAUDE.md needs more explicit instruction — add a line like “Always use WP-CLI to inspect the live install rather than guessing.”

A few WP-CLI patterns worth knowing

These are commands I find Claude Code uses most often during WordPress work, so it’s worth confirming they all work in your environment:

wp plugin list --status=active --format=json
wp option get [option_name]
wp db query "SELECT COUNT(*) FROM wp_posts WHERE post_status='publish'"
wp post list --post_type=any --posts_per_page=5 --format=json
wp eval-file path/to/script.php
wp cron event list
wp transient delete --all

The wp eval-file one is particularly useful: Claude Code can write a one-off PHP script to investigate something, then execute it inside your WordPress runtime via WP-CLI. This sidesteps the limitation that AI can’t normally execute PHP — combined with WP-CLI, it can.

Safety note. Claude Code asks for confirmation before running commands by default. Don’t disable this for WordPress work. WP-CLI can do destructive things (wp db reset, wp post delete --force, wp plugin uninstall), and you want a confirmation step before any of them run. If you want to be extra safe, work against a local copy of your site, not staging or production.

Step 4: Connect MCP servers

MCP servers extend Claude Code beyond shell access. The integrations worth setting up for WordPress:

A MySQL/MariaDB MCP server. Lets Claude inspect your schema, run safe read queries, and (with care) execute writes. Useful when you want structured data access rather than going through wp db query. There are several community options — search for “mysql mcp server” or check the official MCP server registry.

A filesystem MCP server scoped to your project. Claude Code already has filesystem access in its working directory, but a scoped MCP server can give it controlled access to additional paths (like a media directory mounted elsewhere, or a sibling project).

A GitHub MCP server. If your WordPress project lives in GitHub and you want Claude Code to manage issues, PRs, and reviews from the terminal. Less WordPress-specific, more useful in general.

A web search/fetch MCP server. When Claude Code needs to verify a hook exists in WordPress core, look up a function signature, or check current plugin documentation, web access closes the loop. The built-in tools are usually enough, but a dedicated MCP server makes this faster.

Adding an MCP server to Claude Code:

claude mcp add [server-name] [command-or-url]

Or edit your global Claude Code config file directly (location depends on OS — claude config will show you the path). The format is similar to other MCP clients:

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@some-org/mysql-mcp-server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "...",
        "MYSQL_DATABASE": "wordpress"
      }
    }
  }
}

Restart Claude Code and the new MCP tools become available.

The same warning as before: don’t connect MCP servers to production. The point of these integrations is fast, free exploration. Save fast, free exploration for environments where mistakes don’t take down a live site.

Step 5: Create custom slash commands for repeated tasks

Slash commands are the productivity multiplier most Claude Code users miss. They’re saved prompts you can invoke with a single command instead of retyping the full instruction.

Create a .claude/commands/ directory in your project:

mkdir -p .claude/commands

Each markdown file in this directory becomes a slash command. Examples worth creating:

.claude/commands/security-review.md:

Review the changes in this session (or the file I specify) for WordPress
security issues. Specifically check for:

1. Missing output escaping (esc_html, esc_attr, esc_url, wp_kses)
2. Missing input sanitization
3. Missing nonces on forms or AJAX handlers
4. Direct database queries without $wpdb->prepare()
5. Use of deprecated functions
6. Missing capability checks (current_user_can) on privileged operations
7. Unescaped data in JavaScript output
8. Path traversal risks in file operations

Produce a list of findings with severity (critical/high/medium/low) and
the specific fix for each. Do not modify files yet — just produce the report.

Now in any Claude Code session, you type /security-review and the prompt fires.

.claude/commands/explain-codebase.md:

I need to understand this WordPress plugin/theme/codebase. Read through it and produce:

1. A summary of what it does in plain language
2. The main entry points (plugin file, hook registrations, AJAX handlers, etc.)
3. The architecture pattern (MVC? Procedural? Custom framework?)
4. External dependencies and APIs
5. Any concerning patterns (security issues, deprecated code, performance problems)
6. Files I should read first to understand the rest

Don't change anything. This is a read-only investigation.

.claude/commands/modernize-plugin.md:

Audit this plugin for modernization opportunities:

1. Deprecated PHP functions (mysql_*, create_function, etc.)
2. Deprecated WordPress functions
3. Procedural code that would benefit from OOP refactoring
4. Missing namespaces / autoloading
5. jQuery usage that could be vanilla JS
6. Direct file operations that should use WP_Filesystem
7. Direct cURL that should use WordPress HTTP API

Produce a prioritized list. Do not make changes yet.

.claude/commands/test-plugin.md:

Run all available tests for this plugin:

1. Run php -l on every PHP file (syntax check)
2. If PHPCS is configured, run it with the WordPress standard
3. If PHPUnit is configured, run the test suite
4. If npm test is defined, run it
5. Run any custom test commands defined in composer.json or package.json

Report all failures with file/line/error.

Build up your slash command library over time. Whenever you find yourself writing the same prompt twice, save it as a slash command. After a few months you’ll have a personal toolkit that turns common WordPress tasks into one-line operations.

Step 6: Set up agent-friendly output

One quirk of Claude Code: it works much better when your project’s tools produce structured output. A few configuration tweaks that pay off:

WP-CLI: prefer --format=json or --format=csv. These are easier for Claude to parse than the default table format. You can either remember to add the flag, or set environment variables / aliases. I have an alias wpj='wp' and ask Claude to “use json format with WP-CLI” in my CLAUDE.md.

PHPCS: configure phpcs.xml at project root. If the config is in a known location with WordPress standards configured, Claude will run it automatically when checking code quality.

Composer scripts. Add named scripts to composer.json like lint, test, format. Claude Code will discover and run these when relevant.

A short Makefile or package.json scripts. Even better than composer scripts for cross-language projects. Define make test, make lint, make build and Claude can run them on its own.

The pattern: the more deterministic, named commands you have for common operations, the more autonomous Claude Code can be. It doesn’t have to figure out how to test your code — it runs make test.

Step 7: Test the full setup with a real task

Configuration is theoretical until you put it through a real task. Try this:

“Audit the active plugins on this WordPress install for security issues. Use WP-CLI to list them. Read each plugin’s main file and look for: missing nonces, unescaped output, deprecated database functions, and unsafe direct file access. Produce a report grouped by plugin, with severity and specific line references. Don’t fix anything yet.”

A well-configured Claude Code should:

Run wp plugin list --status=active --format=json to get the plugin list
Read each plugin’s main file (and possibly key includes)
Produce a structured report
Stop without modifying anything

If it skips WP-CLI and tries to guess plugin names from your file structure, your CLAUDE.md needs more emphasis on using WP-CLI for runtime data.

If it starts fixing things instead of producing a report, your CLAUDE.md needs more emphasis on the “wait for confirmation before changes” workflow.

Iterate on CLAUDE.md until the test runs cleanly. The few hours you spend tuning the config repay themselves on the first real refactor you delegate to Claude Code.

When to use Claude Code vs Cursor

Now that both are configured, the question is when to use which:

Use Cursor for: Single-file edits, inline refactoring with Cmd+K, writing new code in an existing file, quick “explain this function” questions, and anything where you’re staying in flow inside the editor.

Use Claude Code for: Multi-file refactors, full-codebase audits, plugin modernization, automated workflows (running tests, building assets, deploying), tasks that require WP-CLI access to live data, tasks where the AI benefits from running commands and reading their output, and anything where you’d rather walk away for 30 minutes than hand-hold an agent.

The boundary blurs — Cursor’s agent mode does some of what Claude Code does, and Claude Code can edit single files. But the strengths are real and you’ll naturally develop a feel for which to reach for.

Common setup problems and fixes

“Claude Code can’t find WP-CLI.” Your shell’s PATH in the Claude Code session might differ from your normal terminal. Run which wp in Claude’s session to confirm. If it’s not found, add the absolute path of WP-CLI to your CLAUDE.md and reference it explicitly.

“WP-CLI errors out inside Claude Code but works in my normal terminal.” Common cause: you’re using a Dockerized local environment, and WP-CLI needs to run inside the container. Configure a wrapper command (e.g., wp aliased to docker exec myproject_php wp) and document it in CLAUDE.md.

“Claude keeps making changes without confirming.” Your CLAUDE.md needs stronger language. Try: “NEVER modify files without first describing what you’ll change and waiting for me to approve. The only exception is fixing a typo I explicitly asked you to fix.”

“The MCP server isn’t loading.” Run claude mcp list to confirm it’s registered. Check the server’s logs (location varies by server). Most MCP server issues are environment variable or path issues.

“Costs are higher than expected.” Long sessions with large file reads consume tokens fast. Strategies: use .cursorignore-style patterns to keep large files out of context (Claude Code respects .gitignore by default plus its own ignore files), be explicit about which files to read instead of letting the agent explore freely, and use slash commands to keep prompts focused.

What good Claude Code output looks like

A well-configured Claude Code session for WordPress should feel like working with a focused engineer who knows the codebase. Specifically:

Asks clarifying questions on ambiguous tasks rather than guessing
Uses WP-CLI to verify rather than assuming
States its plan before making non-trivial changes
Runs tests/linters after changes without being asked
Catches its own mistakes when output doesn’t match expectations
Stops when something looks risky and asks for guidance

If your sessions don’t feel like that, the configuration needs more iteration. The setup investment is real — expect to spend a couple of weeks refining CLAUDE.md, slash commands, and conventions before it clicks.