MDX MCP Server

Universal MCP server for intelligent MDX file processing and analysis

Overview

MDX MCP Server is a powerful Model Context Protocol server that enables LLMs to seamlessly interact with, search, and process MDX files. It provides robust tools for reading MDX content as clean Markdown, performing contextual searches, converting files, and extracting metadata, all with built-in cross-platform compatibility and security.

Core Features

Feature	Description
MDX Reading	Convert MDX to clean Markdown format on the fly
Contextual Search	Find content within MDX files with surrounding context
Format Conversion	Convert and save MDX files to standard Markdown
Metadata Extraction	Parse and retrieve YAML frontmatter
Cross-Platform	Native support for Windows, Linux, and macOS
Path Safety	Secure path resolution preventing directory traversal

MCP Tools

The server exposes the following tools through the Model Context Protocol interface.

Tool	Description	Key Parameters
read_mdx	Read an MDX file and return its contents as Markdown	path
search_mdx	Search for content within an MDX file	path, query, contextLines
convert_mdx_to_md	Convert an MDX file to a Markdown file on disk	sourcePath, outputPath
get_mdx_frontmatter	Extract YAML frontmatter from an MDX file	path

Tool Usage Examples

See how the tools can be leveraged to interact with MDX files.

// Read an MDX file
{
  "name": "read_mdx",
  "arguments": {
    "path": "docs/introduction.mdx"
  }
}

// Search with context
{
  "name": "search_mdx",
  "arguments": {
    "path": "docs/guide.mdx",
    "query": "installation",
    "contextLines": 2
  }
}

// Convert MDX to Markdown
{
  "name": "convert_mdx_to_md",
  "arguments": {
    "sourcePath": "docs/guide.mdx",
    "outputPath": "output/guide.md"
  }
}

// Extract metadata
{
  "name": "get_mdx_frontmatter",
  "arguments": {
    "path": "docs/article.mdx"
  }
}

Installation

Prerequisites

Ensure you have Node.js installed:

# Node.js >= 20.19.0 is required
node --version

Install the MCP Server

npm install
npm run build

Configuration

Add to your MCP settings file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "mdx": {
      "command": "node",
      "args": ["/absolute/path/to/mdx-mcp-server/dist/index.js"],
      "env": {
        "WORKSPACE_ROOT": "/path/to/your/workspace"
      }
    }
  }
}

Development

# Clone the repository
git clone https://github.com/LLMTooling/mdx-mcp-server.git
cd mdx-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Architecture

The server follows a modular architecture ensuring clean separation of concerns.

Component	Responsibility
Server Entry	Main MCP server setup and configuration (src/index.ts)
Tools Module	Implementation of individual MCP tools (src/tools/)
Path Resolver	Cross-platform path handling and security (src/utils/path-resolver.ts)
MDX Processor	Core MDX processing logic (src/utils/mdx-processor.ts)

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License