README

Transform your Magento development workflow with AI-powered tools! 🚀

Agento MCP brings the power of Model Context Protocol (MCP) to Magento 2, enabling seamless AI integration with Cursor IDE, Claude, and other AI assistants. Execute SQL queries, manage cache, and access 100+ magerun commands - all through natural language in your IDE.

Why Agento MCP?

⚡ Faster Development: No more context switching between terminal and IDE
🤖 AI-Powered: Natural language commands for Magento operations
🔧 Comprehensive: Access to SQL, cache, magerun, and more
🎯 Developer-Friendly: Built for Magento developers by Magento developers
📦 Easy Installation: Works with any Magento 2.4+ installation
✅ Zero Configuration: Works out of the box after installation

Features

MCP Server Integration: Full Model Context Protocol support for Cursor IDE and other AI tools
SQL Query Execution: Run SQL queries directly through AI chat or command line
Cache Management: Clear Magento cache with simple natural language commands
n98-magerun2 Integration: Access to 100+ magerun commands via AI
Redis Support: Flush Redis cache directly through MCP tools
Multiple Output Formats: JSON, CSV, and table formats for query results
Natural Language Interface: Query admin users, orders, products, and more using plain English

Installation

Option 1: Install via Composer (Recommended)

composer require genaker/agento-mcp
php bin/magento module:enable Agento_Core
php bin/magento setup:upgrade
php bin/magento cache:clean

Option 2: Manual Installation

Clone or download this repository to app/code/Agento/Core
Enable the module:

php bin/magento module:enable Agento_Core
php bin/magento setup:upgrade
php bin/magento cache:clean

Step 3: Install n98-magerun2 (Optional but Recommended)

Agento integrates with n98-magerun2 for additional Magento CLI tools. To install:

cd /var/www/html/magento
curl -sS -o bin/n98-magerun2.phar https://files.magerun.net/n98-magerun2.phar
chmod +x bin/n98-magerun2.phar

Verify installation:

php bin/n98-magerun2.phar --version

For more information, visit: https://github.com/netz98/n98-magerun2

Step 4: Verify Installation

Check that the commands are available:

php bin/magento list | grep agento

You should see:

agento:query - Execute SQL query
agento:cache:clear - Clear cache
agento:mcp - Start MCP server
agento:magerun:install - Install n98-magerun2
agento:cursor:install - Install Cursor MCP server configuration

You should see:

agento:cache:clear - Clear Magento cache
agento:query - Execute SQL query
agento:quick - Clear cache and run query
agento:mcp - Start MCP server

Usage

Execute SQL Query

php bin/magento agento:query --query "SELECT * FROM admin_user LIMIT 5"

With different output formats:

# Table format (default)
php bin/magento agento:query --query "SELECT * FROM admin_user LIMIT 5" --format table

# JSON format
php bin/magento agento:query --query "SELECT * FROM admin_user LIMIT 5" --format json

# CSV format
php bin/magento agento:query --query "SELECT * FROM admin_user LIMIT 5" --format csv

Using a different database connection:

php bin/magento agento:query --query "SELECT * FROM admin_user" --connection indexer

Clear Cache

# Clear all cache
php bin/magento agento:cache:clear

# Clear specific cache type
php bin/magento agento:cache:clear --type config

Cursor Integration (MCP Server)

Quick Install (Recommended)

Run the automated installer:

php bin/magento agento:cursor:install

This command will:

Detect your Magento installation path
Generate the MCP server configuration
Attempt to automatically add it to Cursor settings (if Cursor config is found)
Save the configuration to cursor-mcp-config.json for manual installation

Manual Installation

If automatic installation doesn't work, follow these steps:

Open Cursor settings
Navigate to Features → Model Context Protocol
Add a new MCP server with the following configuration:

For Cursor Settings (JSON):

{
  "mcpServers": {
    "agento": {
      "command": "php",
      "args": [
        "/var/www/html/magento/bin/magento",
        "agento:mcp"
      ],
      "cwd": "/var/www/html/magento"
    }
  }
}

Note: Adjust the paths (/var/www/html/magento) to match your Magento installation directory.

Step 2: Verify MCP Server Connection

Restart Cursor after adding the MCP configuration
The MCP server should automatically connect
You can verify by checking Cursor's MCP server status

Step 3: Test MCP Server

You can test the MCP server manually:

# Start the MCP server (for testing)
php bin/magento agento:mcp

The server will listen on stdin/stdout for JSON-RPC 2.0 protocol messages.

Available MCP Tools

Once connected, the following tools are available to AI assistants:

execute_sql - Execute SQL query against Magento database
- Parameters:
  - query (required): SQL query to execute
  - connection (optional): Database connection name (default: "default")
clear_cache - Clear Magento cache
- Parameters:
  - type (optional): Cache type to clear (clears all if not specified)
magerun - Execute any n98-magerun2 command (Swiss army knife for Magento)
- Parameters:
  - command (required): Full magerun command (e.g., "db:query", "cache:clean", "sys:info", "admin:user:list")
  - arguments (optional): Command arguments as key-value pairs
  - options (optional): Command options as key-value pairs
- Examples:
  - {"command": "sys:info"} - Get system information
  - {"command": "db:query", "arguments": {"query": "SELECT * FROM admin_user LIMIT 5"}} - Run database query
  - {"command": "cache:clean", "options": {"type": "config"}} - Clean specific cache type
  - {"command": "admin:user:list"} - List admin users
magerun_db - Database operations (query, dump, import, info, console, create, drop, status, variables)
- Parameters:
  - command (required): One of: query, dump, import, info, console, create, drop, status, variables
  - arguments (optional): Command-specific arguments
magerun_cache - Cache operations (clean, flush, enable, disable, list, status, view, report)
- Parameters:
  - command (required): One of: clean, flush, enable, disable, list, status, view, report
  - arguments (optional): Command-specific arguments (e.g., {"type": "config"} for clean)
magerun_admin - Admin user management (list, create, change-password, delete, activate, deactivate, unlock)
- Parameters:
  - command (required): One of: user:list, user:create, user:change-password, user:delete, user:activate, user:deactivate, user:unlock, token:create
  - arguments (optional): Command-specific arguments
magerun_sys - System information (info, check, store:list, website:list, url:list, cron:list, cron:run)
- Parameters:
  - command (required): One of: info, check, store:list, website:list, url:list, cron:list, cron:run, maintenance
  - arguments (optional): Command-specific arguments
magerun_config - Configuration management (store:get, store:set, env:set, search, show)
- Parameters:
  - command (required): One of: store:get, store:set, env:set, search, show, show:urls, show:default-url, show:store-url
  - arguments (optional): Command-specific arguments (e.g., {"path": "web/unsecure/base_url"} for store:get)
magerun_customer - Customer management (list, create, info, delete, change-password, add-address)
- Parameters:
  - command (required): One of: list, create, info, delete, change-password, add-address, token:create
  - arguments (optional): Command-specific arguments
magerun_indexer - Indexer operations (reindex, reset, status, set-mode, show-mode, info)
- Parameters:
  - command (required): One of: reindex, reset, status, set-mode, show-mode, info, set-status
  - arguments (optional): Command-specific arguments
magerun_module - Module management (enable, disable, status, uninstall)
- Parameters:
  - command (required): One of: enable, disable, status, uninstall
  - arguments (optional): Command-specific arguments (e.g., {"module": "Magento_Catalog"})
magerun_setup - Setup operations (upgrade, install, db:status, di:compile, static-content:deploy)
- Parameters:
  - command (required): One of: upgrade, install, db:status, di:compile, static-content:deploy, backup, rollback, uninstall
  - arguments (optional): Command-specific arguments

Note: For a complete list of all available magerun commands, visit: https://github.com/netz98/n98-magerun2/tree/develop/docs/docs/command-docs

Testing the Installation

Test 1: Verify Commands are Available

php bin/magento list | grep agento

Expected output:

agento:cache:clear          Clear Magento cache
agento:mcp                  Start Agento MCP server for AI integration
agento:query                Execute SQL query against Magento database
agento:quick                Clear cache and execute SQL query in one command

Test 2: Test SQL Query Command

php bin/magento agento:query --query "SELECT VERSION() as mysql_version"

Expected output:

+-------------------------+
| mysql_version           |
+-------------------------+
| 8.0.42-0ubuntu0.24.04.2 |
+-------------------------+
Rows returned: 1 | Execution time: X.XXms

Test 3: Test Cache Clear Command

php bin/magento agento:cache:clear

Expected: Should show cache types being cleared.

Test 4: Test Quick Command

php bin/magento agento:quick --query "SELECT COUNT(*) as total FROM admin_user"

Expected: Should show:

"Clearing cache..." message
"✓ All cache cleared" or "✓ Cleared cache type: X"
"Executing query..." message
Query results in table format
Row count and execution time

Test 5: Test MCP Server (Manual)

Create a test file test_mcp.json:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Then test:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | php bin/magento agento:mcp

Expected: Should return a JSON response with available tools.

Troubleshooting

Command Not Found

If commands are not available:

php bin/magento module:enable Agento_Core
php bin/magento setup:upgrade
php bin/magento cache:clean

MCP Server Not Connecting

Verify the path to bin/magento is correct in Cursor settings
Ensure PHP is in your system PATH
Check Cursor's MCP server logs for errors
Test the MCP server manually using the test above

Database Connection Errors

Ensure your app/etc/env.php has correct database credentials:

'db' => [
    'connection' => [
        'default' => [
            'host' => '127.0.0.1',
            'dbname' => 'magento',
            'username' => 'magento',
            'password' => 'magento'
        ]
    ]
]

Examples

Example 1: Get All Admin Users

php bin/magento agento:query --query "SELECT user_id, username, email, is_active FROM admin_user"

Example 2: Get Product Count by Status

php bin/magento agento:query --query "SELECT status, COUNT(*) as count FROM catalog_product_entity GROUP BY status"

Example 4: Export Data as JSON

php bin/magento agento:query --query "SELECT * FROM admin_user LIMIT 5" --format json > users.json

Example 5: Using n98-magerun2 Commands

You can also use n98-magerun2 commands directly:

# Get system information
php bin/n98-magerun2.phar sys:info

# Run database query
php bin/n98-magerun2.phar db:query "SELECT * FROM admin_user LIMIT 5"

# List admin users
php bin/n98-magerun2.phar admin:user:list

# Clean cache
php bin/n98-magerun2.phar cache:clean

# Get store list
php bin/n98-magerun2.phar sys:store:list

Note: These commands are also available through the MCP server for AI assistants in Cursor.

Requirements

Magento 2.4.x
PHP 7.4 or higher
MySQL/MariaDB database

License

This module is provided as-is for development purposes.

Testing

Standalone tests are available that run commands as isolated processes (simulating how Cursor/MCP would call them):

# Run all tests
php app/code/Agento/Core/tests/run-standalone-tests.php

See tests/README.md for more details.

Perfect For

Magento developers using Cursor IDE or other AI coding assistants
Development teams wanting to streamline workflows
Developers exploring AI-assisted coding
Anyone managing Magento stores who wants faster access to data and operations

Real-World Examples

Once set up, you can use natural language commands in Cursor:

"Show me all active admin users"
"What's the last order?"
"Clear the config cache"
"How many customers do we have?"
"List all Magento stores"
"Get the customer with the most orders"

The AI will automatically use the appropriate MCP tools to execute these requests!

Support

For issues or questions, please check:

GitHub Repository
Magento documentation
Cursor MCP documentation
Module code in app/code/Agento/Core/
Test suite in app/code/Agento/Core/tests/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - See LICENSE file for details

Built with ❤️ for the Magento community.

agento / core

Maintainers

Details

README

Why Agento MCP?

Features

Installation

Option 1: Install via Composer (Recommended)

Option 2: Manual Installation

Step 3: Install n98-magerun2 (Optional but Recommended)

Step 4: Verify Installation

Usage

Execute SQL Query

Clear Cache

Cursor Integration (MCP Server)

Quick Install (Recommended)

Manual Installation

Step 2: Verify MCP Server Connection

Step 3: Test MCP Server

Available MCP Tools

Testing the Installation

Test 1: Verify Commands are Available

Test 2: Test SQL Query Command

Test 3: Test Cache Clear Command

Test 4: Test Quick Command

Test 5: Test MCP Server (Manual)

Troubleshooting

Command Not Found

MCP Server Not Connecting

Database Connection Errors

Examples

Example 1: Get All Admin Users

Example 2: Get Product Count by Status

Example 4: Export Data as JSON

Example 5: Using n98-magerun2 Commands

Requirements

License

Testing

Perfect For

Real-World Examples

Support

Contributing

License