Skip to main content
Glama

Gravity MCP

by GravityKit
README.md10.4 kB
# GravityMCP A Model Context Protocol (MCP) server for Gravity Forms. Interact with your WordPress forms, feeds, and entries through any MCP-compatible client. [![npm version](https://img.shields.io/npm/v/@gravitykit/gravitymcp.svg)](https://www.npmjs.com/package/@gravitykit/gravitymcp) Built by [GravityKit](https://www.gravitykit.com) 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 1. **Clone the repository** ```bash git clone https://github.com/GravityKit/GravityMCP.git cd GravityMCP npm install ``` 2. **Set up environment** ```bash cp .env.example .env ``` 3. **Configure credentials** in `.env`: ```env GRAVITY_FORMS_CONSUMER_KEY=your_key_here GRAVITY_FORMS_CONSUMER_SECRET=your_secret_here GRAVITY_FORMS_BASE_URL=https://yoursite.com ``` 4. **Generate API credentials** in WordPress: - Go to **Forms → Settings → REST API** - Click **Add Key** - Save the Consumer Key and Secret 5. **Add to Claude Desktop** Edit `~/Library/Application Support/Claude/claude_desktop_config.json`: ```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 pagination - `gf_get_form` - Get complete form configuration - `gf_create_form` - Create new forms with fields - `gf_update_form` - Update existing forms - `gf_delete_form` - Delete forms (requires ALLOW_DELETE=true) - `gf_validate_form` - Validate form data ### Entries (5 tools) - `gf_list_entries` - Search entries with advanced filters - `gf_get_entry` - Get specific entry details - `gf_create_entry` - Create new entries - `gf_update_entry` - Update existing entries - `gf_delete_entry` - Delete entries (requires ALLOW_DELETE=true) ### Field Operations (4 tools) - `gf_add_field` - Add fields with intelligent positioning - `gf_update_field` - Update fields with dependency checking - `gf_delete_field` - Delete fields with cascade options - `gf_list_field_types` - List available field types ### Submissions (2 tools) - `gf_submit_form_data` - Submit forms with full processing - `gf_validate_submission` - Validate without submitting ### Add-ons (7 tools) - `gf_list_feeds` - List all add-on feeds - `gf_get_feed` - Get specific feed configuration - `gf_list_form_feeds` - List feeds for a specific form - `gf_create_feed` - Create new add-on feeds - `gf_update_feed` - Update existing feeds - `gf_patch_feed` - Partially update feed properties - `gf_delete_feed` - Delete add-on feeds ## Usage Examples ### Search Entries ```javascript 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 ```javascript await mcp.call('gf_add_field', { form_id: 1, field_type: 'email', properties: { label: 'Email Address', isRequired: true } }); ``` ### Submit Forms ```javascript 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 key - `GRAVITY_FORMS_CONSUMER_SECRET` - API consumer secret - `GRAVITY_FORMS_BASE_URL` - WordPress site URL ### Optional Settings - `GRAVITY_FORMS_ALLOW_DELETE=false` - Enable delete operations - `GRAVITY_FORMS_TIMEOUT=30000` - Request timeout (ms) - `GRAVITY_FORMS_DEBUG=false` - Enable debug logging ## 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: ```env # 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 ```bash # 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: 1. `GRAVITYMCP_TEST_MODE=true` is set 2. OR `NODE_ENV=test` is set 3. 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: 1. **Test Credential Requirements** - The `setup-test-data` script will **fail by default** if test credentials aren't configured 2. **No Silent Fallbacks** - Scripts that create or modify data won't silently fall back to production 3. **Explicit Production Override** - Production usage requires scary `--force-production` flag with warnings 4. **Clear Error Messages** - Helpful guidance on configuring test credentials when missing 5. **Test Data Prefixing** - All test forms automatically prefixed with "TEST_" for easy identification ### Best Practices 1. **Always configure a test environment** - Use a staging/test WordPress site 2. **Never test on production first** - Validate on test site before production 3. **Keep test credentials separate** - Different API keys for test vs live 4. **Use prefixes for test data** - Makes cleanup easy and identification clear 5. **Enable debug mode for testing** - `GRAVITY_FORMS_DEBUG=true` for detailed logs 6. **Review safety warnings** - Take warnings seriously when they appear ## Testing ```bash # 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 ### Authentication Errors - Confirm API keys are correct - Verify user has appropriate Gravity Forms capabilities - Check Forms → Settings → REST API for key status ### Debug Mode Enable detailed logging: ```env GRAVITY_FORMS_DEBUG=true ``` ## Support - [GitHub Issues](https://github.com/GravityKit/GravityMCP/issues) - [Gravity Forms Documentation](https://docs.gravityforms.com/rest-api-v2/) - [MCP Documentation](https://modelcontextprotocol.io/) ## License GPL-2.0 License - see [LICENSE](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 1. **Fork the repository** - Start by creating your own copy 2. **Create a feature branch** - Keep your changes organized 3. **Add tests** - Ensure reliability with test coverage 4. **Run the test suite** - Verify everything works with `npm run test:all` 5. **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: 1. Update the version in `package.json` 2. Commit your changes 3. Create and push a tag: `git tag v1.0.4 && git push origin v1.0.4` 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](https://github.com/GravityKit/GravityMCP/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!

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/GravityKit/gravity-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server