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
- Parsing: On startup, the server parses the OpenAPI 3.0 swagger.json file
- Indexing: Extracts endpoints, parameters, responses, and schemas
- Storage: Stores data in a local SQLite database with FTS5 indexes
- 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_PATHenvironment variable
- Override with
- Swagger File: Default is
data/swagger.jsonin the package directory- Override with
MAGENTO_API_SWAGGER_PATHenvironment variable
- Override with
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
- No Network Dependency: Works completely offline
- Instant Startup: ~2-5 seconds vs minutes of web scraping
- Structured Data: Access to complete OpenAPI metadata
- Precise Search: Filter by method, category, response code
- Schema Resolution: Navigate complex nested data structures
- Deterministic: No HTML parsing or website structure changes
Example Queries
| Query | Tool | Purpose |
|---|---|---|
["cart"] |
search_endpoints | Find all cart-related endpoints |
["customer", "authentication"] |
search_endpoints | Find customer auth endpoints |
/V1/carts/mine |
get_endpoint_details | Get complete cart endpoint docs |
customer |
search_schemas | Find customer-related schemas |
quote-data-cart-interface |
get_schema | View cart data structure |
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:
- Run verification scripts to diagnose issues
- Check database location and permissions
- Verify swagger.json is valid OpenAPI 3.0 format
Metadata
Release files for iflow-mcp_florinel-chis-magento-api-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_florinel_chis_magento_api_mcp-0.1.0.tar.gz | 107.9 kB | Without provenance | Details for iflow_mcp_florinel_chis_magento_api_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_florinel_chis_magento_api_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_florinel_chis_magento_api_mcp-0.1.0-py3-none-any.whl |
Total release size: 227.3 kB
Release files / iflow_mcp_florinel_chis_magento_api_mcp-0.1.0.tar.gz
| Download URL | iflow_mcp_florinel_chis_magento_api_mcp-0.1.0.tar.gz |
|---|---|
| Size | 107.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
47864dc340f49a8fd49b80e65c0495a8b89640ed959d04617095eb486720655d
|
|
BLAKE2b-256 checksum How to use checksums |
1ab24992fd9ef090480d0e0bc2b2b245a9b94b2fd8ffaf01f7f9fa57c619e798
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.30 {"installer":{"name":"uv","version":"0.9.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_florinel_chis_magento_api_mcp-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_florinel_chis_magento_api_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 119.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f0196ed0df3f2cd4121bf1552d6681e84e0f0cedb63daea54c8308212503601b
|
|
BLAKE2b-256 checksum How to use checksums |
a26079f276605a10201274455f40a0308ea869c4a6cb51f1500ddf9bee8ad363
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.30 {"installer":{"name":"uv","version":"0.9.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_florinel-chis-magento-api-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.