florinel-chis/magento-api-mcp

Magento 2 REST API MCP Server

A local STDIO MCP server that provides tools to search and retrieve Magento 2 REST API documentation from OpenAPI (swagger) specifications.

Features

• Search Endpoints: Full-text search across all Magento 2 REST API endpoints
• Get Endpoint Details: Retrieve complete documentation for specific API endpoints
• List Categories: Browse endpoints by category tags (carts, customers, products, etc.)
• Search Schemas: Find data models and schema definitions
• Get Schema Details: View complete schema/model definitions with all properties
• Offline Operation: Works entirely offline using local swagger.json file
• Fast Startup: Only re-parses if swagger.json has been modified

How it Works

1. Parsing: On startup, the server parses the OpenAPI 3.0 swagger.json file
2. Indexing: Extracts endpoints, parameters, responses, and schemas
3. Storage: Stores data in a local SQLite database with FTS5 indexes
4. Searching: Provides full-text search across paths, descriptions, parameters, and schemas

Installation

Requirements

• Python 3.10 or higher
• uv (recommended) or pip

Install from Source

cd magento-api-mcp
pip install -e .

Usage

Running the Server

magento-api-mcp

The server starts immediately and parses the swagger.json file on first run or when the file has been modified.

Configuration

• Database Location: Default is ~/.mcp/magento-api/database.db
  • Override with MAGENTO_API_DB_PATH environment variable
• Swagger File: Default is data/swagger.json in the package directory
  • Override with MAGENTO_API_SWAGGER_PATH environment variable

Using with an MCP Client

Configure your MCP client to run the magento-api-mcp command:

{
  "mcpServers": {
    "magento-api": {
      "command": "magento-api-mcp"
    }
  }
}

Or with custom swagger file:

{
  "mcpServers": {
    "magento-api": {
      "command": "magento-api-mcp",
      "env": {
        "MAGENTO_API_SWAGGER_PATH": "/path/to/your/swagger.json"
      }
    }
  }
}

MCP Tools

1. search_endpoints

Search for API endpoints using keywords.

Parameters:

• queries: List of 1-3 short keyword queries (e.g., ["cart", "customer"])
• filter_by_method: Optional HTTP method filter (GET, POST, PUT, DELETE)
• filter_by_tag: Optional category filter (e.g., "carts/mine")

Example:

search_endpoints(queries=["cart operations"], filter_by_method="GET")

2. get_endpoint_details

Get complete documentation for a specific endpoint.

Parameters:

• path: Exact API path (e.g., "/V1/carts/mine")
• method: Optional HTTP method (if omitted, returns all methods for this path)

Example:

get_endpoint_details(path="/V1/carts/mine", method="GET")

Returns:

• HTTP method and path
• Category and operation ID
• Summary and description
• Parameters table with types and descriptions
• Request body schema (if applicable)
• Response codes and schemas

3. list_tags

List all available API category tags.

Returns: Hierarchical list of all endpoint categories with counts.

4. search_schemas

Search for data schemas/models by keyword.

Parameters:

• query: Keyword to search for

Example:

search_schemas(query="customer")

5. get_schema

Get complete definition of a schema/model.

Parameters:

• schema_name: Exact schema name (e.g., "quote-data-cart-interface")

Returns: Full schema with type, description, and all properties in JSON format.

Verification Scripts

Test each component independently:

# Test the OpenAPI parser
python3 tests/verify_parser.py

# Test database ingestion
python3 tests/verify_db.py

# Test MCP server and all tools
python3 tests/verify_server.py

Database Schema

The server uses SQLite with the following tables:

• endpoints: All API endpoints with FTS5 index
• parameters: Endpoint parameters
• responses: Response definitions
• schemas: Data model definitions with FTS5 index
• metadata: Ingestion tracking

Advantages Over Web Scraping

1. No Network Dependency: Works completely offline
2. Instant Startup: ~2-5 seconds vs minutes of web scraping
3. Structured Data: Access to complete OpenAPI metadata
4. Precise Search: Filter by method, category, response code
5. Schema Resolution: Navigate complex nested data structures
6. Deterministic: No HTML parsing or website structure changes

Example Queries

Development

Project Structure

magento-api-mcp/
├── magento_api_mcp/
│   ├── __init__.py
│   ├── config.py          # Configuration
│   ├── parser.py          # OpenAPI parser
│   ├── ingest.py          # Database ingestion
│   └── server.py          # MCP server with tools
├── tests/
│   ├── verify_parser.py   # Parser verification
│   ├── verify_db.py       # Database verification
│   └── verify_server.py   # Server verification
├── data/
│   └── swagger.json       # OpenAPI specification
├── pyproject.toml
└── README.md

Adding New Tools

To add new MCP tools, edit magento_api_mcp/server.py and use the @mcp.tool() decorator.

Using Different Swagger Files

The server can work with any OpenAPI 3.0 swagger file. Simply set the MAGENTO_API_SWAGGER_PATH environment variable:

export MAGENTO_API_SWAGGER_PATH=/path/to/different-api-swagger.json
magento-api-mcp

License

MIT

Contributing

Contributions welcome! Please test all changes with the verification scripts before submitting.

Support

For issues or questions, please check:

1. Run verification scripts to diagnose issues
2. Check database location and permissions
3. Verify swagger.json is valid OpenAPI 3.0 format