{"id":33266099,"url":"https://github.com/Automattic/wordpress-mcp","last_synced_at":"2025-12-16T14:01:12.087Z","repository":{"id":290569002,"uuid":"974878688","full_name":"Automattic/wordpress-mcp","owner":"Automattic","description":"WordPress MCP — This repository will be deprecated as stable releases of mcp-adapter become available. Please use https://github.com/WordPress/mcp-adapter for ongoing development and support.","archived":false,"fork":false,"pushed_at":"2025-08-30T00:35:17.000Z","size":921,"stargazers_count":633,"open_issues_count":43,"forks_count":96,"subscribers_count":22,"default_branch":"trunk","last_synced_at":"2025-10-31T04:13:42.659Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://automattic.ai","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Automattic.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-29T12:49:22.000Z","updated_at":"2025-10-31T02:45:19.000Z","dependencies_parsed_at":"2025-04-29T14:28:58.705Z","dependency_job_id":"5bef504d-4e19-4ed9-bd79-b90915933d3b","html_url":"https://github.com/Automattic/wordpress-mcp","commit_stats":null,"previous_names":["automattic/wordpress-mcp"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/Automattic/wordpress-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automattic%2Fwordpress-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automattic%2Fwordpress-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automattic%2Fwordpress-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automattic%2Fwordpress-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Automattic","download_url":"https://codeload.github.com/Automattic/wordpress-mcp/tar.gz/refs/heads/trunk","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automattic%2Fwordpress-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27765951,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-16T02:00:10.477Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-11-17T07:00:34.360Z","updated_at":"2025-12-16T14:01:12.081Z","avatar_url":"https://github.com/Automattic.png","language":"PHP","funding_links":[],"categories":["📚 Projects (1974 total)","📦 Other","可用服务"],"sub_categories":["MCP Servers","生产力工具"],"readme":"This repository will be deprecated as the [mcp-adapter](https://github.com/wordpress/mcp-adapter) AI Building Block for WordPress continues releasing stable versions.  \n\nThe shift aligns with two important developments:\n- The [Abilities API](https://github.com/WordPress/abilities-api) is moving into WordPress Core as of version 6.9.\n- mcp-adapter is now stable and will become the canonical plugin and Composer package for MCP integration in WordPress.\n\nWe encourage all users to migrate to mcp-adapter. Future work, including new features and fixes, will happen there. This repository will remain available in archived form for historical reference.\n\n# WordPress MCP\n\n[![Latest Release](https://img.shields.io/github/v/release/Automattic/wordpress-mcp)](https://github.com/Automattic/wordpress-mcp/releases)\n\nA comprehensive WordPress plugin that implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) to expose WordPress functionality through standardized interfaces. This plugin enables AI models and applications to interact with WordPress sites securely using multiple transport protocols and enterprise-grade authentication.\n\n## Features\n\n-   **Dual Transport Protocols**: STDIO and HTTP-based (Streamable) transports\n-   **JWT Authentication**: Secure token-based authentication with management UI\n-   **Admin Interface**: React-based token management and settings dashboard\n-   **AI-Friendly APIs**: JSON-RPC 2.0 compliant endpoints for AI integration\n-   **Extensible Architecture**: Custom tools, resources, and prompts support\n-   **WordPress Feature API**: Adapter for standardized WordPress functionality\n-   **Experimental REST API CRUD Tools**: Generic tools for any WordPress REST API endpoint\n-   **Comprehensive Testing**: 200+ test cases covering all protocols and authentication\n-   **High Performance**: Optimized routing and caching mechanisms\n-   **Enterprise Security**: Multi-layer authentication and audit logging\n\n## Architecture\n\nThe plugin implements a dual transport architecture:\n\n```\nWordPress MCP Plugin\n├── Transport Layer\n│   ├── McpStdioTransport (/wp/v2/wpmcp)\n│   └── McpStreamableTransport (/wp/v2/wpmcp/streamable)\n├── Authentication\n│   └── JWT Authentication System\n├── Method Handlers\n│   ├── Tools, Resources, Prompts\n│   └── System \u0026 Initialization\n└── Admin Interface\n    └── React-based Token Management\n```\n\n### Transport Protocols\n\n| Protocol       | Endpoint                  | Format          | Authentication      | Use Case             |\n| -------------- | ------------------------- | --------------- | ------------------- | -------------------- |\n| **STDIO**      | `/wp/v2/wpmcp`            | WordPress-style | JWT + App Passwords | Legacy compatibility |\n| **Streamable** | `/wp/v2/wpmcp/streamable` | JSON-RPC 2.0    | JWT only            | Modern AI clients    |\n\n## Installation\n\n### Quick Install\n\n1. Download `wordpress-mcp.zip` from [releases](https://github.com/Automattic/wordpress-mcp/releases/)\n2. Upload to `/wp-content/plugins/wordpress-mcp` directory\n3. Activate through WordPress admin 'Plugins' menu\n4. Navigate to `Settings \u003e WordPress MCP` to configure\n\n### Composer Install (Development)\n\n```bash\ncd wp-content/plugins/\ngit clone https://github.com/Automattic/wordpress-mcp.git\ncd wordpress-mcp\ncomposer install --no-dev\nnpm install \u0026\u0026 npm run build\n```\n\n## Authentication Setup\n\n### JWT Token Generation\n\n1. Go to `Settings \u003e WordPress MCP \u003e Authentication Tokens`\n2. Select token duration (1-24 hours)\n3. Click \"Generate New Token\"\n4. Copy the token for use in your MCP client\n\n### MCP Client Configuration\n\n#### Claude Desktop Configuration using [mcp-wordpress-remote](https://github.com/Automattic/mcp-wordpress-remote) proxy\n\nAdd to your Claude Desktop `claude_desktop_config.json`:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"wordpress-mcp\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [ \"-y\", \"@automattic/mcp-wordpress-remote@latest\" ],\n\t\t\t\"env\": {\n\t\t\t\t\"WP_API_URL\": \"https://your-site.com/\",\n\t\t\t\t\"JWT_TOKEN\": \"your-jwt-token-here\",\n\t\t\t\t\"LOG_FILE\": \"optional-path-to-log-file\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n#### Using Application Passwords (Alternative)\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"wordpress-mcp\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [ \"-y\", \"@automattic/mcp-wordpress-remote@latest\" ],\n\t\t\t\"env\": {\n\t\t\t\t\"WP_API_URL\": \"https://your-site.com/\",\n\t\t\t\t\"WP_API_USERNAME\": \"your-username\",\n\t\t\t\t\"WP_API_PASSWORD\": \"your-application-password\",\n\t\t\t\t\"LOG_FILE\": \"optional-path-to-log-file\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n#### VS Code MCP Extension (Direct Streamable Transport)\n\nAdd to your VS Code MCP settings:\n\n```json\n{\n\t\"servers\": {\n\t\t\"wordpress-mcp\": {\n\t\t\t\"type\": \"http\",\n\t\t\t\"url\": \"https://your-site.com/wp-json/wp/v2/wpmcp/streamable\",\n\t\t\t\"headers\": {\n\t\t\t\t\"Authorization\": \"Bearer your-jwt-token-here\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n#### MCP Inspector (Development/Testing)\n\n```bash\n# Using JWT Token with proxy\nnpx @modelcontextprotocol/inspector \\\n  -e WP_API_URL=https://your-site.com/ \\\n  -e JWT_TOKEN=your-jwt-token-here \\\n  npx @automattic/mcp-wordpress-remote@latest\n\n# Using Application Password with proxy\nnpx @modelcontextprotocol/inspector \\\n  -e WP_API_URL=https://your-site.com/ \\\n  -e WP_API_USERNAME=your-username \\\n  -e WP_API_PASSWORD=your-application-password \\\n  npx @automattic/mcp-wordpress-remote@latest\n```\n\n#### Local Development Configuration\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"wordpress-local\": {\n\t\t\t\"command\": \"node\",\n\t\t\t\"args\": [ \"/path/to/mcp-wordpress-remote/dist/proxy.js\" ],\n\t\t\t\"env\": {\n\t\t\t\t\"WP_API_URL\": \"http://localhost:8080/\",\n\t\t\t\t\"JWT_TOKEN\": \"your-local-jwt-token\",\n\t\t\t\t\"LOG_FILE\": \"optional-path-to-log-file\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n## Usage\n\n### With MCP Clients\n\nThis plugin works seamlessly with MCP-compatible clients in two ways:\n\n**Via Proxy:**\n\n-   [mcp-wordpress-remote](https://github.com/Automattic/mcp-wordpress-remote) - Official MCP client with enhanced features\n-   Claude Desktop with proxy configuration for full WordPress and WooCommerce support\n-   Any MCP client using the STDIO transport protocol\n\n**Direct Streamable Transport:**\n\n-   VS Code MCP Extension connecting directly to `/wp/v2/wpmcp/streamable`\n-   Custom HTTP-based MCP implementations using JSON-RPC 2.0\n-   Any client supporting HTTP transport with JWT authentication\n\nThe streamable transport provides a direct JSON-RPC 2.0 compliant endpoint, while the proxy offers additional features like WooCommerce integration, enhanced logging, and compatibility with legacy authentication methods.\n\n### Available MCP Methods\n\n| Method           | Description              | Transport Support |\n| ---------------- | ------------------------ | ----------------- |\n| `initialize`     | Initialize MCP session   | Both              |\n| `tools/list`     | List available tools     | Both              |\n| `tools/call`     | Execute a tool           | Both              |\n| `resources/list` | List available resources | Both              |\n| `resources/read` | Read resource content    | Both              |\n| `prompts/list`   | List available prompts   | Both              |\n| `prompts/get`    | Get prompt template      | Both              |\n\n### Experimental REST API CRUD Tools\n\n**EXPERIMENTAL FEATURE**: This functionality is experimental and may change or be removed in future versions.\n\nWhen enabled via `Settings \u003e WordPress MCP \u003e Enable REST API CRUD Tools`, the plugin provides three powerful generic tools that can interact with any WordPress REST API endpoint:\n\n#### Available Tools\n\n| Tool Name              | Description                                         | Type   |\n| ---------------------- | --------------------------------------------------- | ------ |\n| `list_api_functions`   | Discover all available WordPress REST API endpoints | Read   |\n| `get_function_details` | Get detailed metadata for specific endpoint/method  | Read   |\n| `run_api_function`     | Execute any REST API function with CRUD operations  | Action |\n\n#### Usage Workflow\n\n1. **Discovery**: Use `list_api_functions` to see all available endpoints\n2. **Inspection**: Use `get_function_details` to understand required parameters\n3. **Execution**: Use `run_api_function` to perform CRUD operations\n\n#### Security \u0026 Permissions\n\n-   **User Capabilities**: All operations respect current user permissions\n-   **Settings Control**: Individual CRUD operations can be disabled in settings:\n    -   Enable Create Tools (POST operations)\n    -   Enable Update Tools (PATCH/PUT operations)\n    -   Enable Delete Tools (DELETE operations)\n-   **Automatic Filtering**: Excludes sensitive endpoints (JWT auth, oembed, autosaves, revisions)\n\n#### Benefits\n\n-   **Universal Access**: Works with any WordPress REST API endpoint, including custom post types and third-party plugins\n-   **AI-Friendly**: Provides discovery and introspection capabilities for AI agents\n-   **Standards Compliant**: Uses standard HTTP methods (GET, POST, PATCH, DELETE)\n-   **Permission Safe**: Inherits WordPress user capabilities and respects endpoint permissions\n\n## Development\n\n### Project Structure\n\n```\nwp-content/plugins/wordpress-mcp/\n├── includes/                   # PHP classes\n│   ├── Core/                  # Transport and core logic\n│   ├── Auth/                  # JWT authentication\n│   ├── Tools/                 # MCP tools\n│   ├── Resources/             # MCP resources\n│   ├── Prompts/               # MCP prompts\n│   └── Admin/                 # Settings interface\n├── src/                       # React components\n│   └── settings/              # Admin UI components\n├── tests/                     # Test suite\n│   └── phpunit/              # PHPUnit tests\n└── docs/                      # Documentation\n```\n\n### Adding Custom Tools\n\nYou can extend the MCP functionality by adding custom tools through your own plugins or themes. Create a new tool class in your plugin or theme:\n\n```php\n\u003c?php\ndeclare(strict_types=1);\n\nnamespace Automattic\\WordpressMcp\\Tools;\n\nclass MyCustomTool {\n    public function register(): void {\n        add_action('wp_mcp_register_tools', [$this, 'register_tool']);\n    }\n\n    public function register_tool(): void {\n        WPMCP()-\u003eregister_tool([\n            'name' =\u003e 'my_custom_tool',\n            'description' =\u003e 'My custom tool description',\n            'inputSchema' =\u003e [\n                'type' =\u003e 'object',\n                'properties' =\u003e [\n                    'param1' =\u003e ['type' =\u003e 'string', 'description' =\u003e 'Parameter 1']\n                ],\n                'required' =\u003e ['param1']\n            ],\n            'callback' =\u003e [$this, 'execute'],\n        ]);\n    }\n\n    public function execute(array $args): array {\n        // Your tool logic here\n        return ['result' =\u003e 'success'];\n    }\n}\n```\n\n### Adding Custom Resources\n\nYou can extend the MCP functionality by adding custom resources through your own plugins or themes. Create a new resource class in your plugin or theme:\n\n```php\n\u003c?php\ndeclare(strict_types=1);\n\nnamespace Automattic\\WordpressMcp\\Resources;\n\nclass MyCustomResource {\n    public function register(): void {\n        add_action('wp_mcp_register_resources', [$this, 'register_resource']);\n    }\n\n    public function register_resource(): void {\n        WPMCP()-\u003eregister_resource([\n            'uri' =\u003e 'custom://my-resource',\n            'name' =\u003e 'My Custom Resource',\n            'description' =\u003e 'Custom resource description',\n            'mimeType' =\u003e 'application/json',\n            'callback' =\u003e [$this, 'get_content'],\n        ]);\n    }\n\n    public function get_content(): array {\n        return ['contents' =\u003e [/* resource data */]];\n    }\n}\n```\n\n### Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Run all tests\nvendor/bin/phpunit\n\n# Run specific test suites\nvendor/bin/phpunit tests/phpunit/McpStdioTransportTest.php\nvendor/bin/phpunit tests/phpunit/McpStreamableTransportTest.php\nvendor/bin/phpunit tests/phpunit/JwtAuthTest.php\n\n# Run with coverage\nvendor/bin/phpunit --coverage-html coverage/\n```\n\n### Building Frontend\n\n```bash\n# Development build\nnpm run dev\n\n# Production build\nnpm run build\n\n# Watch mode\nnpm run start\n```\n\n## Security\n\n### Best Practices\n\n-   **Token Management**: Use shortest expiration time needed (1-24 hours)\n-   **User Permissions**: Tokens inherit user capabilities\n-   **Secure Storage**: Never commit tokens to repositories\n-   **Regular Cleanup**: Revoke unused tokens promptly\n-   **Access Control**: Streamable transport requires admin privileges\n-   **CRUD Operations**: Only enable create/update/delete tools when necessary\n-   **Experimental Features**: Use REST API CRUD tools with caution in production environments\n\n### Security Features\n\n-   JWT signature validation\n-   Token expiration and revocation\n-   User capability inheritance\n-   Secure secret key generation\n-   Audit logging for security events\n-   Protection against malformed requests\n\n## Testing Coverage\n\nThe plugin includes extensive testing:\n\n-   **Transport Testing**: Both STDIO and Streamable protocols\n-   **Authentication Testing**: JWT generation, validation, and revocation\n-   **Integration Testing**: Cross-transport comparison\n-   **Security Testing**: Edge cases and malformed requests\n-   **Performance Testing**: Load and stress testing\n\nView detailed testing documentation in [`tests/README.md`](tests/README.md).\n\n## Configuration\n\n### Environment Variables\n\n```php\n// wp-config.php\ndefine('WPMCP_JWT_SECRET_KEY', 'your-secret-key');\ndefine('WPMCP_DEBUG', true); // Enable debug logging\n```\n\n### Plugin Settings\n\nAccess via `Settings \u003e WordPress MCP`:\n\n-   **Enable/Disable MCP**: Toggle plugin functionality\n-   **Transport Configuration**: Configure STDIO/Streamable transports\n-   **Feature Toggles**: Enable/disable specific tools and resources\n-   **CRUD Operation Controls**: Granular control over create, update, and delete operations\n-   **Experimental Features**: Enable REST API CRUD Tools (experimental functionality)\n-   **Authentication Settings**: JWT token management\n\n#### CRUD Operation Settings\n\nThe plugin provides granular control over CRUD operations:\n\n-   **Enable Create Tools**: Allow POST operations via MCP tools\n-   **Enable Update Tools**: Allow PATCH/PUT operations via MCP tools\n-   **Enable Delete Tools**: ⚠️ Allow DELETE operations via MCP tools (use with caution)\n-   **Enable REST API CRUD Tools**: 🧪 Enable experimental generic REST API access tools\n\n**Security Note**: Delete operations can permanently remove data. Only enable delete tools if you trust all users with MCP access.\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md).\n\n### Development Setup\n\n1. Clone the repository\n2. Run `composer install` for PHP dependencies\n3. Run `npm install` for JavaScript dependencies\n4. Set up WordPress test environment\n5. Run tests with `vendor/bin/phpunit`\n\n## Documentation\n\n-   **Documentation Overview**: [docs/README.md](docs/README.md)\n-   **Client Setup Guide**: [docs/client-setup.md](docs/client-setup.md)\n-   **AI Integration Guide**: [docs/for-ai.md](docs/for-ai.md)\n-   **Registered Tools**: [docs/registered-tools.md](docs/registered-tools.md)\n-   **Registered Resources**: [docs/registered-resources.md](docs/registered-resources.md)\n-   **Registered Prompts**: [docs/registered-prompts.md](docs/registered-prompts.md)\n-   **Register MCP Tools**: [docs/register-mcp-tools.md](docs/register-mcp-tools.md)\n-   **Register MCP Prompts**: [docs/register-mcp-prompt.md](docs/register-mcp-prompt.md)\n-   **Register MCP Resources**: [docs/register-mcp-resources.md](docs/register-mcp-resources.md)\n-   **Troubleshooting Guide**: [docs/troubleshooting.md](docs/troubleshooting.md)\n-   **Testing Guide**: [tests/README.md](tests/README.md)\n\n## Support\n\nFor support and questions:\n\n-   **Documentation**: [docs/README.md](docs/README.md)\n-   **Bug Reports**: [GitHub Issues](https://github.com/Automattic/wordpress-mcp/issues)\n-   **Discussions**: [GitHub Discussions](https://github.com/Automattic/wordpress-mcp/discussions)\n-   **Contact**: Reach out to the maintainers\n\n## License\n\nThis project is licensed under the [GPL v2 or later](LICENSE).\n\n---\n\nBuilt with ❤️ by [Automattic](https://automattic.com) for the WordPress and AI communities.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAutomattic%2Fwordpress-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAutomattic%2Fwordpress-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAutomattic%2Fwordpress-mcp/lists"}