MCP for Gravity Forms
A Model Context Protocol (MCP) server for Gravity Forms. Interact with your WordPress forms, feeds, and entries through any MCP-compatible client.
Built by GravityKit for the Gravity Forms community.
Features
- Comprehensive API Coverage: Gravity Forms API endpoints
- Smart Field Management: Intelligent field operations with dependency tracking
- Advanced Search: Complex filtering and searching capabilities for entries
- Form Submissions: Full submission workflow with validation
- Add-on Integration: Manage feeds for MailChimp, Stripe, PayPal, and more
- Type-Safe: Comprehensive validation for all operations
- Battle-Tested: Extensive test suite with real-world scenarios
Quick Start
Prerequisites
- Node.js 18+
- WordPress with Gravity Forms 2.5+
- HTTPS-enabled WordPress site (required for authentication)
Installation
-
Clone the repository
git clone https://github.com/GravityKit/GravityMCP.git cd GravityMCP npm install -
Set up environment
cp .env.example .env -
Configure credentials in
.env:GRAVITY_FORMS_CONSUMER_KEY=your_key_here GRAVITY_FORMS_CONSUMER_SECRET=your_secret_here GRAVITY_FORMS_BASE_URL=https://yoursite.comFor local development (Laravel Valet, MAMP, etc.):
# Add this line if using self-signed certificates MCP_ALLOW_SELF_SIGNED_CERTS=true -
Generate API credentials in WordPress:
- Go to Forms → Settings → REST API
- Click Add Key
- Save the Consumer Key and Secret
-
Add to Claude Desktop
Edit
~/Library/Application Support/Claude/claude_desktop_config.json:{ "mcpServers": { "gravitymcp": { "command": "node", "args": ["/path/to/GravityMCP/src/index.js"], "env": { "GRAVITY_FORMS_CONSUMER_KEY": "your_key", "GRAVITY_FORMS_CONSUMER_SECRET": "your_secret", "GRAVITY_FORMS_BASE_URL": "https://yoursite.com" } } } }
Available Tools
Forms (6 tools)
gf_list_forms- List forms with filtering and paginationgf_get_form- Get complete form configurationgf_create_form- Create new forms with fieldsgf_update_form- Update existing formsgf_delete_form- Delete forms (requires ALLOW_DELETE=true)gf_validate_form- Validate form data
Entries (5 tools)
gf_list_entries- Search entries with advanced filtersgf_get_entry- Get specific entry detailsgf_create_entry- Create new entriesgf_update_entry- Update existing entriesgf_delete_entry- Delete entries (requires ALLOW_DELETE=true)
Field Operations (4 tools)
gf_add_field- Add fields with intelligent positioninggf_update_field- Update fields with dependency checkinggf_delete_field- Delete fields with cascade optionsgf_list_field_types- List available field types
Submissions (2 tools)
gf_submit_form_data- Submit forms with full processinggf_validate_submission- Validate without submitting
Add-ons (7 tools)
gf_list_feeds- List all add-on feedsgf_get_feed- Get specific feed configurationgf_list_form_feeds- List feeds for a specific formgf_create_feed- Create new add-on feedsgf_update_feed- Update existing feedsgf_patch_feed- Partially update feed propertiesgf_delete_feed- Delete add-on feeds
Usage Examples
Search Entries
await mcp.call('gf_list_entries', {
search: {
field_filters: [
{ key: "1.3", value: "John", operator: "contains" },
{ key: "date_created", value: "2024-01-01", operator: ">=" }
],
mode: "all"
},
sorting: { key: "date_created", direction: "desc" }
});
Add Fields
await mcp.call('gf_add_field', {
form_id: 1,
field_type: 'email',
properties: {
label: 'Email Address',
isRequired: true
}
});
Submit Forms
await mcp.call('gf_submit_form_data', {
form_id: 1,
input_1: "John Doe",
input_2: "john@example.com",
input_3: "Message content"
});
Configuration
Required Environment Variables
GRAVITY_FORMS_CONSUMER_KEY- API consumer keyGRAVITY_FORMS_CONSUMER_SECRET- API consumer secretGRAVITY_FORMS_BASE_URL- WordPress site URL
Optional Settings
GRAVITY_FORMS_ALLOW_DELETE=false- Enable delete operationsGRAVITY_FORMS_TIMEOUT=30000- Request timeout (ms)GRAVITY_FORMS_DEBUG=false- Enable debug loggingMCP_ALLOW_SELF_SIGNED_CERTS=false- Allow self-signed SSL certificates (local dev only)
Test Environment Configuration
The server supports dual environment configuration to safely test without affecting production data.
Setting Up Test Environment
Add test site credentials to your .env file alongside production credentials:
# Production/Live Site
GRAVITY_FORMS_CONSUMER_KEY=ck_live_key
GRAVITY_FORMS_CONSUMER_SECRET=cs_live_secret
GRAVITY_FORMS_BASE_URL=https://www.yoursite.com
# Test/Staging Site (recommended for safe testing)
GRAVITY_FORMS_TEST_CONSUMER_KEY=ck_test_key
GRAVITY_FORMS_TEST_CONSUMER_SECRET=cs_test_secret
GRAVITY_FORMS_TEST_BASE_URL=https://staging.yoursite.com
# Enable test mode (optional)
GRAVITY_MCP_TEST_MODE=true
Test Environment Features
When using test configuration:
- Automatic test form prefixing - All test forms created with "TEST_" prefix
- Auto-cleanup - Test forms automatically removed after testing
- Environment isolation - Complete separation from production data
- Safe experimentation - Test destructive operations without risk
Using Test Mode
# Verify test environment configuration
GRAVITY_MCP_TEST_MODE=true npm run check-env
# Create test data on test site (requires test credentials)
npm run setup-test-data
# Run all tests against test site (auto-detects test credentials)
npm test
# Interactive testing with MCP Inspector (test mode)
GRAVITYMCP_TEST_MODE=true npm run inspect
# Run specific test suites against test site
NODE_ENV=test npm run test:forms
NODE_ENV=test npm run test:entries
NODE_ENV=test npm run test:submissions
Test Mode Detection
The server automatically uses test configuration when:
GRAVITYMCP_TEST_MODE=trueis set- OR
NODE_ENV=testis set - OR test credentials are configured and test commands are run
Test Safety Features
The server includes multiple safety mechanisms to prevent accidental production data contamination:
- Test Credential Requirements - The
setup-test-datascript will fail by default if test credentials aren't configured - No Silent Fallbacks - Scripts that create or modify data won't silently fall back to production
- Explicit Production Override - Production usage requires scary
--force-productionflag with warnings - Clear Error Messages - Helpful guidance on configuring test credentials when missing
- Test Data Prefixing - All test forms automatically prefixed with "TEST_" for easy identification
Best Practices
- Always configure a test environment - Use a staging/test WordPress site
- Never test on production first - Validate on test site before production
- Keep test credentials separate - Different API keys for test vs live
- Use prefixes for test data - Makes cleanup easy and identification clear
- Enable debug mode for testing -
GRAVITY_FORMS_DEBUG=truefor detailed logs - Review safety warnings - Take warnings seriously when they appear
Testing
# Run all tests
npm run test:all
# Run specific test suites
npm run test:forms
npm run test:entries
npm run test:field-operations
# Run with live API (requires credentials)
npm test
Security
- HTTPS Required: All API communication encrypted
- Delete Protection: Destructive operations disabled by default
- Input Validation: All inputs validated before API calls
- Rate Limiting: Automatic retry with exponential backoff
Troubleshooting
Connection Issues
- Verify credentials with
npm run check-env - Ensure WordPress site is HTTPS-enabled
- Check REST API is enabled in Gravity Forms settings
Local Development with Self-Signed Certificates
If you're using a local development environment (Laravel Valet, MAMP, Local WP, etc.) with self-signed SSL certificates, you may encounter authentication errors. To fix this:
Add to your .env file:
MCP_ALLOW_SELF_SIGNED_CERTS=true
⚠️ Security Warning: Only disable SSL certificate verification for local development environments. Never use this setting in production!
Authentication Errors
- Confirm API keys are correct
- Verify user has appropriate Gravity Forms capabilities
- Check Forms → Settings → REST API for key status
- For local development, ensure
MCP_ALLOW_SELF_SIGNED_CERTS=trueis set if using self-signed certificates
Debug Mode
Enable detailed logging:
GRAVITY_FORMS_DEBUG=true
Support
License
GPL-2.0 License - see LICENSE file for details.
Contributing
We welcome contributions from the Gravity Forms community! Whether you're building add-ons, managing forms, or integrating with other services, your insights and code contributions can help everyone.
How to Contribute
- Fork the repository - Start by creating your own copy
- Create a feature branch - Keep your changes organized
- Add tests - Ensure reliability with test coverage
- Run the test suite - Verify everything works with
npm run test:all - Submit a pull request - Share your improvements with the community
Automated Publishing
This repository uses GitHub Actions to automatically publish to npm when a new version is tagged:
- Update the version in
package.json - Commit your changes
- Create and push a tag:
git tag v1.0.4 && git push origin v1.0.4 - GitHub Actions will automatically publish to npm
Note for maintainers: Ensure the NPM_TOKEN secret is configured in the repository settings for automated publishing to work.
Contribution Ideas
For Add-on Developers:
- Add support for your add-on's feed types
- Enhance field type definitions for custom fields
- Share integration patterns that work well
For Form Builders:
- Improve field validation logic
- Add helper utilities for common tasks
- Enhance error messages and debugging
For Everyone:
- Report bugs or suggest features via GitHub Issues
- Improve documentation and examples
- Share your use cases and workflows
Your contributions help make Gravity Forms automation better for everyone. Let's build something great together!