Reading the repo
Opening the box…
Reading the repo
Opening the box…
How to install on Windows
WordPress MCP server with 234 Free tools and 547 total with Pro for building pages, managing content, and operating your site. Availability depends on installed integrations and enabled tools.
Saved setup from 2 h ago
Will it work on Windows?
Also: Docs ↗
CONTRIBUTING.mdThanks for being here. Bug reports, docs fixes, prompts, and new tools are all genuinely useful, and you don't need to write PHP to help.
User documentation lives at emcptools.com/docs. This file is about working on the plugin itself.
| | What it involves |
|---|---|
| Report a bug | The most valuable thing you can do. Include your MCP client, the tool you called, and what came back. |
| Improve the docs | The docs live in the website repo, but if something in this repo is wrong or stale, a PR fixing it is very welcome. |
| Contribute a prompt | A landing-page blueprint in prompts/. No PHP needed, see Contributing prompts. |
| Add a tool | A new MCP ability in an existing domain. See Adding a tool. |
| Add an integration | Support for a plugin we don't cover yet. This is the highest-leverage code contribution, see Adding an integration. |
Requirements: WordPress 6.9+, PHP 8.1+, Composer, and WP-CLI (strongly recommended). Elementor is optional: most domains work without it, install it if you're touching the page-building tools. The MCP Adapter and the Abilities API are bundled, so there's nothing extra to install.
cd /path/to/wordpress/wp-content/plugins
git clone https://github.com/msrbuilds/elementor-mcp.git emcp-tools
cd emcp-tools
composer install
Activate the plugin, then confirm the server registered:
wp mcp-adapter list --path=/path/to/wordpress
To poke at tools interactively:
npx @modelcontextprotocol/inspector wp mcp-adapter serve \
--server=emcp-tools-server --user=admin --path=/path/to/wordpress
Note on the
pro/directory. The Pro tier lives in a separate private repository, mounted as a git submodule atpro/. A normal clone simply won't have it, and the plugin runs fine without it, every Pro unit is guarded. If you see references topro/in the code, that's why.
emcp-tools/
├── emcp-tools.php # Bootstrap: header, constants, requires, init
├── includes/
│ ├── class-bootstrap.php # Loads every class, wires hooks
│ ├── class-plugin.php # Singleton orchestrator
│ ├── class-elementor-data.php # Elementor document read/write layer
│ ├── class-element-factory.php # Builds valid Elementor JSON
│ ├── abilities/ # MCP tools, grouped by domain
│ │ ├── class-ability-registrar.php # Registers every group
│ │ ├── class-query-abilities.php # Discovery (Elementor)
│ │ ├── class-content-abilities.php # WordPress content
│ │ ├── forms/ # Form-plugin integrations
│ │ ├── seo/ # SEO-plugin integrations
│ │ └── addons/ # Elementor addon packs (Pro)
│ ├── modules/ # Toggleable features (Modules tab)
│ ├── themer/ # EMCP Themer (theme builder)
│ ├── security/ · performance/ # Scanners
│ ├── schemas/ · validators/ # Control-to-JSON-Schema, input validation
│ └── admin/ # Admin screens
├── prompts/ # Landing-page blueprints
└── tests/ # Public test suite
Key ideas:
_elementor_data directly. Go through the data layer, it triggers CSS regeneration and cache busting. Raw meta writes cause bugs that only appear on the front end.Add it to the ability class for its domain, or create a new class if it genuinely doesn't fit.
1. Register it. Use the emcp_tools_register_ability() wrapper, not wp_register_ability() directly:
emcp_tools_register_ability(
'emcp-tools/my-new-tool',
array(
'label' => __( 'My New Tool', 'emcp-tools' ),
'description' => __( 'What it does, written for an AI agent deciding whether to call it.', 'emcp-tools' ),
'category' => 'emcp-tools',
'input_schema' => array(
'type' => 'object',
'properties' => array(
'post_id' => array(
'type' => 'integer',
'description' => __( 'The page/post ID.', 'emcp-tools' ),
),
),
'required' => array( 'post_id' ),
),
'permission_callback' => array( $this, 'check_edit_permission' ),
'execute_callback' => array( $this, 'execute_my_new_tool' ),
)
);
categoryis required. Leave it out andwp_register_ability()drops the ability silently, with no error. The tool simply never appears. This has bitten us more than once.
2. Implement it. Return an array on success, a WP_Error on failure. Never return a bare false.
3. Register the group in class-ability-registrar.php, and add the tool to get_all_tools() in includes/admin/class-admin.php so it appears on the Tools tab.
4. If it writes, deletes, or affects the whole site, ship it disabled by default: bump DEFAULTS_VERSION in the admin class and seed your slug. Destructive tools should also require confirm: true.
Descriptions are a UX surface. An agent picks tools by reading them, so write for that reader: say what it does and when to use it, not just what it's called.
Support for a third-party plugin is the most useful code contribution, and it follows a fixed shape: two dispatcher tools, <plugin>-read and <plugin>-write, each taking { operation, arguments }. That keeps the tool list small no matter how many plugins we support.
Look at includes/abilities/forms/ or includes/abilities/seo/ for working examples. Both have an abstract base class doing the dispatching, so a new adapter is mostly a map of operations.
Rules that matter:
confirm: true.Please open an integration request before starting a large one, so we can agree the operation list first.
A prompt is a complete landing-page blueprint in prompts/. Include a design system (colours, typography, spacing), the full page structure, image search keywords, and the execution order. Use one of the existing files as your template, and name it INDUSTRY_NAME.md in caps with underscores.
Test it end to end against a real site before submitting: paste it into your AI client and confirm the page actually builds.
WordPress coding standards, strictly.
snake_case functions and variables, Upper_Snake_Case classes, UPPER_SNAKE constants.EMCP_Tools_ for classes, emcp_tools_ for functions, hooks, and options.emcp-tools. Every user-facing string goes through __() / esc_html__().$wpdb->prepare() for SQL, verify nonces, check capabilities before anything privileged.The public suite needs no private submodule:
composer install
vendor/bin/phpunit -c tests/phpunit.xml
Put new tests in tests/, named SomethingTest.php. Test the pure logic, validators, schema mapping, dispatcher routing, permission delegation, rather than trying to boot WordPress.
Test the trap, not just the happy path. The most valuable tests we have pin down behaviour that silently breaks: a permission that must not escalate, a signature that must not appear verbatim on disk, a confirm gate that must refuse. If you fixed a bug, add the test that would have caught it.
main (git checkout -b feature/my-tool).php -l on every file you touched.CHANGELOG.md entry describing the change from a user's point of view.main.Guidelines:
Use the bug report template. The details that actually speed up a fix:
wp-content/debug.logFor anything security-sensitive, please don't open a public issue. Email hello@msrbuilds.com instead.
Every contribution helps, including the ones that just tell us something is broken. Thank you.
Then run powershell -ExecutionPolicy Bypass -File .\setup.ps1. It stops at the first error and is safe to run again. Servers and tests aren't started; it lists them at the end. Read it first.
Needs Git: winget install Git.Git. The repo uses git submodules, so the clone fetches them too.
git clone --recurse-submodules https://github.com/msrbuilds/elementor-mcp.git cd elementor-mcp
Node.js 22, PHP >=8.1
winget install CoreyButler.NVMforWindows nvm install 22 nvm use 22 scoop install php composer # needs scoop: https://scoop.sh
npm ci composer install
npm run start
npm test
emcp-tools-*.zip from Releases.Free installs update in place from Dashboard → Updates.
Requires WordPress 6.9+ and PHP 8.1+. Elementor 3.20+ is optional (4.0+ for atomic elements). The MCP Adapter is included (the official plugin is used instead when it is active); the Abilities API is in WordPress core.
No reports for Windows yet.
GitManual AI Agent reads the 8 key files and writes a step-by-step guide for Windows. Once written, it's saved for everyone.