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)

How it Works

1. Parsing: On startup, the server parses markdown files with YAML frontmatter
2. Extraction: Extracts metadata, code blocks, and GraphQL schema elements
3. Indexing: Stores data in SQLite with FTS5 full-text search indexes
4. 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 data

Option 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 ~/.zshrc

Step 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-mcp

Auto-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-mcp

Host-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-dock

... [View full README on GitHub](https://github.com/florinel-chis/magento-graphql-docs-mcp#readme)