Magento 2 GraphQL Documentation MCP Server
Provides search and retrieval tools for Magento 2 GraphQL API documentation, including queries, mutations, types, interfaces, code examples, and tutorials for building e-commerce integrations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Magento 2 GraphQL Documentation MCP Server show me how to create a customer with GraphQL"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Magento 2 GraphQL Documentation MCP Server
A local STDIO MCP server that provides tools to search and retrieve Magento 2 GraphQL API documentation from local markdown files.
π New to setup? See SETUP.md for a step-by-step quick start guide.
Features
Search Documentation: Full-text search across 350+ GraphQL documentation pages
Get Complete Documents: Retrieve full documentation with metadata
Search GraphQL Elements: Find queries, mutations, types, and interfaces
Get Element Details: View complete schema element definitions with examples
Browse Categories: Navigate documentation hierarchy (schema, develop, usage, tutorials)
Access Tutorials: Get step-by-step learning paths (e.g., checkout workflow)
Search Code Examples: Find working code examples in GraphQL, JSON, JavaScript
Discover Related Docs: Find related documentation automatically
Offline Operation: Works entirely offline using local markdown files
Fast Startup: Only re-indexes if documentation files have changed (<5 seconds)
Related MCP server: GraphQL Schema Explorer
How it Works
Parsing: On startup, the server parses markdown files with YAML frontmatter
Extraction: Extracts metadata, code blocks, and GraphQL schema elements
Indexing: Stores data in SQLite with FTS5 full-text search indexes
Searching: Provides intelligent search across documentation, code, and schema
Quick Start
Step 1: Clone the Documentation Repository
The MCP server requires access to the Adobe Commerce GraphQL documentation markdown files. Clone the official repository:
# Clone the commerce-webapi repository
git clone https://github.com/AdobeDocs/commerce-webapi.git
# The GraphQL docs are located at:
# commerce-webapi/src/pages/graphql/Step 2: Set Up the Documentation Path
You have two options for configuring the documentation path:
Option A: Using a Symlink (Recommended)
Create a symlink in the project directory:
cd magento-graphql-docs-mcp
ln -s /path/to/commerce-webapi/src/pages/graphql dataOption B: Using Environment Variable
Set the MAGENTO_GRAPHQL_DOCS_PATH environment variable:
export MAGENTO_GRAPHQL_DOCS_PATH="/path/to/commerce-webapi/src/pages/graphql"To make this permanent, add it to your shell profile (~/.bashrc, ~/.zshrc, etc.):
echo 'export MAGENTO_GRAPHQL_DOCS_PATH="/path/to/commerce-webapi/src/pages/graphql"' >> ~/.zshrc
source ~/.zshrcStep 3: Verify Documentation Access
Check that the documentation path is accessible:
# If using symlink:
ls -la data/
# If using environment variable:
ls -la $MAGENTO_GRAPHQL_DOCS_PATH/
# You should see files like:
# - index.md
# - release-notes.md
# - schema/ (directory)
# - tutorials/ (directory)
# - develop/ (directory)Step 4: Install the MCP Server
cd magento-graphql-docs-mcp
pip install -e .(Optional) Build and Run with Docker
If you prefer Docker, build the image and mount your docs path to /data (or set MAGENTO_GRAPHQL_DOCS_PATH to another location):
docker build -t magento-graphql-docs-mcp -f docker/Dockerfile .
docker run --rm -it \
-v /absolute/path/to/commerce-webapi/src/pages/graphql:/data \
magento-graphql-docs-mcpAuto-fetch fallback: if you do not mount docs, the container can clone them on start. Control this with MAGENTO_GRAPHQL_DOCS_AUTO_FETCH (default: true):
# Let the container clone docs (uses /tmp/commerce-webapi/src/pages/graphql)
docker run --rm -it magento-graphql-docs-mcp
# Disable auto-fetch; require a mount or preset MAGENTO_GRAPHQL_DOCS_PATH
docker run --rm -it \
-e MAGENTO_GRAPHQL_DOCS_AUTO_FETCH=false \
-v /absolute/path/to/commerce-webapi/src/pages/graphql:/data \
magento-graphql-docs-mcpHost-Side Docker Wrapper (STDIO)
Use the provided wrapper to run the container and forward STDIN/STDOUT for MCP clients (no TTY added):
# From repo root
./run-docker-mcp.shWhat it does:
Builds the
magento-graphql-docs-mcpimage automatically if it is missingMounts
MAGENTO_GRAPHQL_DOCS_PATH(or./data) to/dataif it exists; otherwise relies on auto-fetchKeeps STDIO clean for MCP clients; prints connection instructions on start
Respects
MAGENTO_GRAPHQL_DOCS_AUTO_FETCH(set tofalseto require a mounted path)
Point your MCP client command to the wrapper path. Example Claude Desktop config:
{
"mcpServers": {
"magento-graphql-docs": {
"command": "/absolute/path/to/run-docker-mcp.sh"
}
}
}VS Code MCP Configuration
Example VS Code MCP config using the Docker wrapper:
{
"servers": {
"magento-webapi-docs": {
"type": "stdio",
"command": "/absolute/path/to/run-docker-mcp.sh"
}
}
}After adding the server entry, open the VS Code MCP/Tools panel and press βStartβ for magento-webapi-docs to launch the container-backed STDIO server.
Docker Compose (HTTP/SSE)
Use the provided docker-compose.yml to run the server on HTTP/SSE:
docker compose up --buildThis builds from docker/Dockerfile, maps 8765:8765, and sets MAGENTO_GRAPHQL_DOCS_TRANSPORT=http with MAGENTO_GRAPHQL_DOCS_HOST=0.0.0.0. Uncomment the volumes block in docker-compose.yml to bind a local docs checkout; otherwise the image can auto-fetch the docs. Port 8765 is chosen to avoid common 8080 conflicts; adjust as needed.
Step 5: Run and Verify
# Run the server (will parse and index 350 documents on first run)
magento-graphql-docs-mcp
# In another terminal, run verification tests:
python3 tests/verify_parser.py
python3 tests/verify_db.py
python3 tests/verify_server.pyInstallation
Requirements
Python 3.10 or higher
Git (to clone the documentation repository)
350+ Magento 2 GraphQL documentation markdown files from AdobeDocs/commerce-webapi
Detailed Setup
1. Clone Both Repositories
# Clone the documentation source
git clone https://github.com/AdobeDocs/commerce-webapi.git
# Clone this MCP server
cd magento-graphql-docs-mcp2. Configure Documentation Path
The server looks for documentation in this order (with path validation on startup):
Environment variable
MAGENTO_GRAPHQL_DOCS_PATH(if set, validates path exists)./data/directory (symlink or directory with .md files in project root)../commerce-webapi/src/pages/graphql/(sibling directory auto-detection)
If no valid path is found, the server will fail with a helpful error message explaining all three setup options.
Choose the method that works best for your setup:
# Method 1: Symlink (recommended for development)
ln -s ~/projects/commerce-webapi/src/pages/graphql data
# Method 2: Environment variable (recommended for deployment)
export MAGENTO_GRAPHQL_DOCS_PATH="$HOME/projects/commerce-webapi/src/pages/graphql"
# Method 3: Clone commerce-webapi as sibling directory
# magento-graphql-docs-mcp/
# commerce-webapi/
# βββ src/pages/graphql/3. Install Dependencies
pip install -e .This installs:
fastmcp- MCP server frameworksqlite-utils- Database managementpydantic- Data validationpython-frontmatter- YAML frontmatter parsingmarkdown-it-py- Markdown processing
Usage
Running the Server
Once configured, start the server:
# Start the MCP server
magento-graphql-docs-mcp
# The server will:
# 1. Check if documentation has changed (compares file modification times)
# 2. Parse markdown files if needed (350 files, ~3-5 seconds)
# 3. Index content in SQLite with FTS5
# 4. Start listening for MCP requests over STDIOOn subsequent runs, if the documentation hasn't changed, startup is nearly instant (~0.87s).
Running Over HTTP/SSE
STDIO remains the default. To expose the server via HTTP with SSE (for clients that expect MCP over SSE), set the transport variables:
MAGENTO_GRAPHQL_DOCS_TRANSPORT=http \
MAGENTO_GRAPHQL_DOCS_HOST=0.0.0.0 \
MAGENTO_GRAPHQL_DOCS_PORT=8765 \
magento-graphql-docs-mcpMAGENTO_GRAPHQL_DOCS_HOST defaults to 127.0.0.1 and MAGENTO_GRAPHQL_DOCS_PORT defaults to 8765 when unset. Port 8765 is frequently used by other services; pick any free port (example above uses the default port 8765).
Configuration
The server uses environment variables for configuration:
Documentation Path
Set where the GraphQL documentation is located:
# Option 1: Absolute path (recommended)
export MAGENTO_GRAPHQL_DOCS_PATH="/Users/you/projects/commerce-webapi/src/pages/graphql"
# Option 2: Relative path (from project root)
export MAGENTO_GRAPHQL_DOCS_PATH="./data"
# Option 3: Home directory relative
export MAGENTO_GRAPHQL_DOCS_PATH="~/repos/commerce-webapi/src/pages/graphql"Default: The server looks for documentation in these locations (in order, with validation):
MAGENTO_GRAPHQL_DOCS_PATHenvironment variable (validated on startup)./data/directory in project root (must contain .md files)../commerce-webapi/src/pages/graphql/(sibling directory auto-detection)
Database Location
Customize where the SQLite database is stored:
# Default: ~/.mcp/magento-graphql-docs/database.db
export MAGENTO_GRAPHQL_DOCS_DB_PATH="/custom/path/magento-graphql.db"The database directory will be created automatically if it doesn't exist.
Performance Tuning (Optional)
Customize search behavior and limits:
# Number of search results to return (default: 5)
export MAGENTO_GRAPHQL_DOCS_TOP_K=10
# Max fields per GraphQL element (default: 20)
export MAGENTO_GRAPHQL_DOCS_MAX_FIELDS=30
# Max code preview length in characters (default: 400)
export MAGENTO_GRAPHQL_DOCS_CODE_PREVIEW=600Transport & Port
Control how the MCP server is exposed:
MAGENTO_GRAPHQL_DOCS_TRANSPORT:stdio(default) orhttp/sseto enable HTTP + SSEMAGENTO_GRAPHQL_DOCS_HOST: bind address for HTTP/SSE mode (default:127.0.0.1)MAGENTO_GRAPHQL_DOCS_PORT: HTTP/SSE port (default:8765)
FastMCP serves SSE when transport="http".
Using with an MCP Client
Configure your MCP client (e.g., Claude Desktop, Cline, etc.) to use this server.
Example: Claude Desktop Configuration
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"magento-graphql-docs": {
"command": "magento-graphql-docs-mcp",
"env": {
"MAGENTO_GRAPHQL_DOCS_PATH": "/Users/you/projects/commerce-webapi/src/pages/graphql"
}
}
}
}Example: Using Python Module Directly
{
"mcpServers": {
"magento-graphql-docs": {
"command": "python3",
"args": ["-m", "magento_graphql_docs_mcp.server"],
"env": {
"MAGENTO_GRAPHQL_DOCS_PATH": "/path/to/commerce-webapi/src/pages/graphql"
}
}
}
}Example: With Custom Database Path
{
"mcpServers": {
"magento-graphql-docs": {
"command": "magento-graphql-docs-mcp",
"env": {
"MAGENTO_GRAPHQL_DOCS_PATH": "/path/to/commerce-webapi/src/pages/graphql",
"MAGENTO_GRAPHQL_DOCS_DB_PATH": "/custom/databases/magento-graphql.db"
}
}
}
}After configuration, restart your MCP client to activate the server.
Usage Examples
The examples/ directory contains practical usage examples demonstrating all MCP tools:
Available Examples
Product Queries (
examples/example_products.py)Search product documentation
Find product GraphQL queries and types
Explore ProductInterface details
Search product code examples
Customer Queries (
examples/example_customer.py)Search customer documentation
Find customer mutations (create, update)
Explore authentication and tokens
Find customer address operations
Cart & Checkout (
examples/example_cart_checkout.py)Search cart documentation
Complete checkout workflow tutorial
Find cart mutations and queries
Explore checkout step-by-step
Running Examples
# Run individual examples
python3 examples/example_products.py
python3 examples/example_customer.py
python3 examples/example_cart_checkout.py
# Or run all examples at once
bash examples/run_all_examples.shSee examples/README.md for detailed documentation.
MCP Tools
1. search_documentation
Search for documentation pages using keywords.
Parameters:
queries: List of 1-3 short keyword queries (e.g., ["product", "cart"])category: Optional filter (schema, develop, usage, tutorials)subcategory: Optional filter (products, cart, customer, etc.)content_type: Optional filter (guide, reference, tutorial, schema)
Example:
search_documentation(queries=["checkout"], category="tutorials")2. get_document
Get complete documentation page by file path.
Parameters:
file_path: Relative path to document (e.g., "schema/products/queries/products.md")
Returns: Full document content with metadata, frontmatter, and markdown.
3. search_graphql_elements
Search for GraphQL queries, mutations, types, or interfaces.
Parameters:
query: Search termelement_type: Optional filter (query, mutation, type, interface, union)
Example:
search_graphql_elements(query="products", element_type="query")4. get_element_details
Get complete details about a specific GraphQL element.
Parameters:
element_name: Element name (e.g., "products", "createCustomer")element_type: Optional type filter
Returns: Full element definition with fields, parameters, source document, and code examples.
5. list_categories
List all documentation categories with document counts.
Returns: Hierarchical category tree showing all available documentation areas.
6. get_tutorial
Get complete tutorial with all steps in order.
Parameters:
tutorial_name: Tutorial name (e.g., "checkout")
Returns: Sequential tutorial steps with code examples and explanations.
7. search_examples
Search for code examples by topic and language.
Parameters:
query: Search termlanguage: Optional language filter (graphql, json, javascript, php, bash)
Example:
search_examples(query="add to cart", language="graphql")8. get_related_documents
Find documents related to a specified document.
Parameters:
file_path: File path of source document
Returns: Related documents based on category and keywords.
Verification Scripts
Test each component independently.
Important: Run all tests from the project root directory:
# Navigate to project root
cd magento-graphql-docs-mcp
# Test the markdown parser
python3 tests/verify_parser.py
# Test database ingestion
python3 tests/verify_db.py
# Test MCP server and all 8 tools
python3 tests/verify_server.py
# Run performance benchmarks
python3 tests/benchmark_performance.pyRunning tests from other directories will cause import errors.
Database Schema
The server uses SQLite with the following tables:
documents: All documentation pages with FTS5 index
code_blocks: Code examples from documentation
graphql_elements: Extracted GraphQL schema elements with FTS5 index
metadata: Ingestion tracking
Performance
Based on benchmarks (run python3 tests/benchmark_performance.py):
Startup Time: 0.87s (when data unchanged) | 3-5s (first run or files changed)
Search Speed: 5.5ms average (FTS5 direct: 0.7ms)
Document Retrieval: 8.2ms
GraphQL Element Search: 3.4ms
Database Size: ~30 MB for 350 documents
Indexed Content: 350 documents, 963 code blocks, 51 GraphQL elements
All performance targets exceeded: <5s startup β, <100ms searches β
Example Queries
Query | Tool | Result |
"How do I query products?" | search_documentation | Product query documentation |
"Show me product query details" | search_graphql_elements | products query definition |
"Complete checkout flow" | get_tutorial | Step-by-step checkout guide |
"Cart mutation examples" | search_examples | Working GraphQL cart examples |
"All B2B documentation" | list_categories + search | B2B schema documentation |
Development
Project Structure
magento-graphql-docs-mcp/
βββ magento_graphql_docs_mcp/
β βββ __init__.py
β βββ config.py # Configuration
β βββ parser.py # Markdown + GraphQL parser
β βββ ingest.py # Database ingestion
β βββ server.py # MCP server with 8 tools
βββ tests/
β βββ verify_parser.py # Parser verification
β βββ verify_db.py # Database verification
β βββ verify_server.py # Server verification
βββ data/
β βββ (symlink to docs)
βββ pyproject.toml
βββ README.md
βββ CLAUDE.mdArchitecture
Markdown Files (350)
β
Parser (frontmatter + content + GraphQL extraction)
β
SQLite (documents + code_blocks + graphql_elements + FTS5)
β
FastMCP Server (8 tools via STDIO)
β
MCP Client (Claude, IDE, etc.)Advantages
vs Web Scraping
β Offline operation (no network required)
β Fast startup (3-5s vs 30-60s)
β Local control (works with custom docs)
β No HTML parsing complexity
vs REST API MCP
β Includes tutorials and guides (not just API specs)
β Code examples searchable
β Narrative content for learning
β Tutorial workflows
Unique Features
π 350 documents indexed
π 8 specialized search tools
π‘ Tutorial support
π Code example search
π Related document discovery
β‘ Fast FTS5 search
π― GraphQL-aware parsing
Troubleshooting
Documentation Not Found Error
Error: FileNotFoundError: Documentation directory not found!
The server now provides a helpful error message showing all three setup methods.
Solutions:
Verify the documentation repository is cloned:
git clone https://github.com/AdobeDocs/commerce-webapi.gitCheck the path is correct:
# If using environment variable: echo $MAGENTO_GRAPHQL_DOCS_PATH ls -la $MAGENTO_GRAPHQL_DOCS_PATH # If using symlink: ls -la data/ # Should show a symlink pointing to the GraphQL docs # You should see 350+ markdown files and directories like: # - schema/ # - tutorials/ # - develop/ # - index.mdSet the correct path (choose one method):
# Method 1: Environment variable (recommended for deployment) export MAGENTO_GRAPHQL_DOCS_PATH="/path/to/commerce-webapi/src/pages/graphql" # Method 2: Create symlink (recommended for development) cd magento-graphql-docs-mcp ln -s /path/to/commerce-webapi/src/pages/graphql data # Verify: ls -la data/ should show the symlink # Method 3: Clone as sibling directory (automatic) cd parent-directory git clone https://github.com/AdobeDocs/commerce-webapi.git # Server will automatically find itVerify the setup:
# The server validates paths on startup and will show helpful errors magento-graphql-docs-mcp # If path is invalid, you'll see exactly which methods were tried
Server Won't Start
Error: ModuleNotFoundError: No module named 'magento_graphql_docs_mcp'
Solution: Install the package in development mode:
cd magento-graphql-docs-mcp
pip install -e .Error: Server starts but immediately exits
Solution: Check Python version (requires 3.10+):
python3 --version # Should be 3.10 or higherNo Search Results
Issue: Search returns no results even though documentation exists
Solutions:
Use shorter, simpler keywords:
# Instead of: "customer authentication token generation" # Try: ["customer", "token"] # Instead of: "how to add products to cart" # Try: ["cart", "add"]Check if database was created:
ls -la ~/.mcp/magento-graphql-docs/ # Should show database.db (around 30 MB)Verify data was indexed:
python3 tests/verify_db.py # Should show: 350 documents, 963 code blocks, 51 GraphQL elementsRe-index the database:
rm ~/.mcp/magento-graphql-docs/database.db magento-graphql-docs-mcp # Will parse and re-index everything
Database Errors
Error: sqlite3.OperationalError: database is locked
Solution: Another process is using the database:
# Find and kill the process
lsof ~/.mcp/magento-graphql-docs/database.db
kill <PID>
# Or simply remove and recreate
rm ~/.mcp/magento-graphql-docs/database.db
magento-graphql-docs-mcpError: sqlite3.DatabaseError: database disk image is malformed
Solution: Database is corrupted, recreate it:
rm -rf ~/.mcp/magento-graphql-docs/
magento-graphql-docs-mcp # Will recreate from scratchSlow Performance
Issue: First startup takes >10 seconds
Solution: This is normal! First run parses 350 files. Subsequent runs are <1s.
Issue: Every startup is slow
Solution: Documentation mtime is changing. Check:
# Verify git isn't changing file times
cd /path/to/commerce-webapi
git status
git pull # Update to latest if neededVerification Failed
Issue: verify_server.py fails with connection errors
Solution:
# Ensure dependencies are installed
pip install -e ".[dev]"
# Check MCP client libraries
pip list | grep mcp
# Re-run individual verifications
python3 tests/verify_parser.py # Test parsing
python3 tests/verify_db.py # Test database
python3 tests/verify_server.py # Test MCP serverMCP Client Integration Issues
Issue: MCP client shows "Server not found" or "Connection failed"
Solutions:
Verify command is correct:
# Test the command directly which magento-graphql-docs-mcp # or python3 -m magento_graphql_docs_mcp.serverCheck environment variables in MCP config:
{ "mcpServers": { "magento-graphql-docs": { "command": "magento-graphql-docs-mcp", "env": { "MAGENTO_GRAPHQL_DOCS_PATH": "/FULL/PATH/to/commerce-webapi/src/pages/graphql" } } } }Important: Use absolute paths, not
~or relative paths in MCP config.Check logs:
Claude Desktop:
~/Library/Logs/Claude/(macOS)Look for error messages related to the server
Getting Help
If you're still having issues:
Run all verification scripts:
python3 tests/verify_parser.py python3 tests/verify_db.py python3 tests/verify_server.py python3 tests/benchmark_performance.pyCheck your setup:
# Python version python3 --version # Documentation path echo $MAGENTO_GRAPHQL_DOCS_PATH ls -la $MAGENTO_GRAPHQL_DOCS_PATH | head -20 # Database ls -la ~/.mcp/magento-graphql-docs/ # Package installation pip show magento-graphql-docs-mcpCreate a GitHub issue with the output of the above commands.
License
MIT
Contributing
Contributions welcome! Please test all changes with verification scripts before submitting.
Support
For issues or questions:
Run verification scripts to diagnose issues
Check database location and permissions
Verify documentation path is correct
Available Tools
8 toolsget_documentB
Retrieve complete documentation page by file path
Inputs: file_path (required). Returns: result
get_element_detailsA
Get complete details about a specific GraphQL element
Inputs: element_name (required), element_type. Returns: result
get_tutorialB
Get complete tutorial with all steps in order
Inputs: tutorial_name (required). Returns: result
list_categoriesA
List all documentation categories with document counts
Inputs: no named parameters. Returns: result
search_documentationA
Search Magento 2 GraphQL documentation by keywords. Use SHORT keyword queries (1-3 words) to find documentation pages. Can filter by category, subcategory, or content type.
Inputs: queries (required), category, subcategory, content_type. Returns: result
search_examplesC
Search for code examples by topic and language
Inputs: query (required), language. Returns: result
search_graphql_elementsB
Search for GraphQL queries, mutations, types, or interfaces
Inputs: query (required), element_type. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 8 tools
Each tool has a distinct purpose: retrieving documents by path, element details, related documents, tutorials, categories, and different search types. No overlap.
All tools use consistent lowercase with underscores and follow a verb_noun pattern (get_, list_, search_), with predictable naming.
8 tools is well-suited for a documentation server, covering all essential operations without excess or deficiency.
The tool set provides comprehensive coverage for documentation access: direct retrieval, tutorials, categories, and multiple search modes (keywords, examples, elements).
Maintenance
Related MCP Connectors
Search and read Apple developer documentation, HIG, and WWDC transcripts as Markdown.
Get up-to-date, version-specific documentation and code examples from official sources directly inβ¦
Provides tools for searching Google Workspace documentation and much more.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables querying and exploring the GitHub GraphQL API schema and executing optimized GraphQL queries to retrieve precise GitHub data (repositories, issues, PRs, users) with reduced token consumption.-
- FlicenseNot gradedqualityDmaintenanceProvides intelligent introspection and exploration of any GraphQL API schema with fuzzy search, type discovery, and field-level information to help understand and navigate GraphQL APIs.-
- FlicenseAqualityDmaintenanceEnables searching and retrieving Magento 2 REST API documentation offline via local OpenAPI parsing, supporting endpoint search, schema lookup, and category browsing.57-
- AlicenseAqualityBmaintenanceEnables AI agents to shop and query Magento/Mage-OS stores via the storefront GraphQL API, including product search, stock checks, category browsing, cart management, and customer order status.11MIT