Markdown MCP Server

A Model Context Protocol (MCP) server that extracts clean markdown content from web pages using Playwright. This server provides a get_page_markdown tool that can extract the main content from any URL while filtering out navigation, headers, footers, and other non-content elements.

Features

🎯 Smart Content Extraction: Automatically identifies and extracts main content from web pages
🧹 Clean Output: Filters out navigation, headers, footers, sidebars, and advertisements
🎨 Rich Markdown: Preserves formatting including headings, bold, italic, code blocks, lists, and tables
🖼️ Image Support: Optionally includes image references in markdown
🔗 Link Support: Optionally includes hyperlinks in markdown
⚡ Fast & Reliable: Uses Playwright for robust web scraping
🔄 Dynamic Content: Handles JavaScript-heavy sites and dynamic content loading
🛡️ Error Handling: Robust error handling with fallback extraction methods

Installation

Clone or download this repository:
git clone <repository-url> cd markdown-mcp
Install dependencies:
npm install
Install Playwright browsers:
npx playwright install chromium
Make the script executable (optional):
chmod +x markdown-mcp.js

Usage

As an MCP Server

Start the server:

node markdown-mcp.js

The server provides one tool: get_page_markdown

Tool Parameters

url (required): The URL to extract markdown from
includeImages (optional, default: true): Whether to include image references in markdown
includeLinks (optional, default: true): Whether to include hyperlinks in markdown
waitForSelector (optional): CSS selector to wait for before extracting content (useful for dynamic content)
timeout (optional, default: 30000): Navigation timeout in milliseconds

Example Usage

{ "name": "get_page_markdown", "arguments": { "url": "https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html", "includeImages": true, "includeLinks": true, "timeout": 30000 } }

Advanced Usage Examples

Extract content from a specific section:

{ "name": "get_page_markdown", "arguments": { "url": "https://example.com/article", "waitForSelector": ".main-content", "includeImages": false, "includeLinks": true } }

Extract content with custom timeout:

{ "name": "get_page_markdown", "arguments": { "url": "https://slow-loading-site.com", "timeout": 60000 } }

File Structure

This project includes two MCP server files optimized for different clients:

markdown-mcp.js - Optimized for Claude Desktop
markdown-mcp-gemini.js - Optimized for Gemini CLI

Both files provide the same get_page_markdown tool but are configured differently for optimal performance with each client.

Adding to AI Clients

This MCP server can be used with multiple AI clients that support the Model Context Protocol. Below are instructions for the most popular clients.

Claude Desktop Integration

To use this MCP server with Claude Desktop, you need to add it to your Claude Desktop configuration file.

Step 1: Locate Claude Desktop Configuration

macOS:

Configuration file: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

Configuration file: %APPDATA%\Claude\claude_desktop_config.json

Linux:

Configuration file: ~/.config/claude/claude_desktop_config.json

Step 2: Edit Configuration File

Open the configuration file in a text editor
Add the markdown-mcp server to the mcpServers section
Update the path to point to your markdown-mcp.js file

Step 3: Configuration Examples

macOS Configuration

{ "mcpServers": { "markdown-mcp": { "command": "node", "args": ["/Users/yourusername/path/to/markdown-mcp/markdown-mcp.js"], "env": {} } } }

Windows Configuration

{ "mcpServers": { "markdown-mcp": { "command": "node", "args": ["C:\\Users\\YourUsername\\path\\to\\markdown-mcp\\markdown-mcp.js"], "env": {} } } }

Linux Configuration

{ "mcpServers": { "markdown-mcp": { "command": "node", "args": ["/home/yourusername/path/to/markdown-mcp/markdown-mcp.js"], "env": {} } } }

Step 4: Restart Claude Desktop

After updating the configuration file, restart Claude Desktop for the changes to take effect.

Step 5: Verify Installation

Open Claude Desktop
Start a new conversation
Try asking Claude to extract content from a webpage using the markdown-mcp tool
Example: "Use markdown-mcp to extract content from https://example.com"

Troubleshooting

If the MCP server doesn't work:

Check the file path - Make sure the path to markdown-mcp.js is correct and the file exists
Verify Node.js - Ensure Node.js is installed and accessible from the command line
Check permissions - Make sure the script has execute permissions
Test manually - Try running node markdown-mcp.js in the terminal to see if there are any errors
Check Claude Desktop logs - Look for error messages in Claude Desktop's developer console

Common Issues:

Path not found: Double-check the file path in the configuration
Node.js not found: Make sure Node.js is installed and in your PATH
Permission denied: Run chmod +x markdown-mcp.js to make the script executable
Dependencies missing: Run npm install in the markdown-mcp directory

Gemini CLI Integration

To use this MCP server with Gemini CLI, follow these steps:

Step 1: Install Gemini CLI

If you haven't already installed Gemini CLI:

npm install -g @google/gemini-cli

Verify the installation:

gemini --version

Step 2: Add MCP Server to Gemini CLI

Add your markdown-mcp server to Gemini CLI:

gemini mcp add markdown-mcp /Users/yourusername/path/to/markdown-mcp/markdown-mcp-gemini.js

Important: Replace /Users/yourusername/path/to/markdown-mcp/markdown-mcp-gemini.js with the actual path to your markdown-mcp-gemini.js file.

Step 3: Verify Integration

List all configured MCP servers to verify the integration:

gemini mcp list

You should see markdown-mcp listed among the servers.

Step 4: Test the Integration

Test the markdown-mcp server with Gemini CLI:

# Example: Extract content from a webpage gemini "Use the markdown-mcp tool to extract content from https://example.com"

Or you can use the tool directly:

# If the tool is exposed as a command gemini get_page_markdown "https://example.com"

Step 5: Complete Example - Extract and Save Markdown

Here's a complete example that extracts markdown content and saves it to a file:

# Extract content from a webpage and save to result.md gemini "Use get_page_markdown to extract content from https://www.confluent.io/blog/event-driven-flink-agents-enterprise-ai/ and save the response as result.md"

This command will:

Use the get_page_markdown tool to extract clean markdown content from the Confluent blog post
Save the extracted markdown content to a file named result.md in your current directory
Provide you with a clean, readable markdown version of the webpage content

Additional Examples:

# Extract content from documentation and save with custom filename gemini "Use get_page_markdown to extract content from https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html and save it as flink-docs.md" # Extract content from a GitHub repository README gemini "Use get_page_markdown to extract content from https://github.com/microsoft/vscode and save as vscode-readme.md" # Extract content with specific options gemini "Use get_page_markdown with includeImages=false to extract content from https://example.com and save as clean-content.md"

Gemini CLI Troubleshooting

If the MCP server doesn't work with Gemini CLI:

Check the file path - Ensure the path to markdown-mcp-gemini.js is correct and absolute
Verify Node.js - Make sure Node.js is accessible from the command line
Check permissions - Ensure the script has execute permissions (chmod +x markdown-mcp-gemini.js)
Test the server manually - Run node markdown-mcp-gemini.js to check for errors
Check Gemini CLI logs - Look for error messages in the Gemini CLI output

Common Gemini CLI Issues:

Path not found: Use absolute paths when adding the MCP server
Permission denied: Run chmod +x markdown-mcp-gemini.js to make the script executable
Node.js not found: Ensure Node.js is installed and in your PATH
Server not responding: Check if the server starts correctly with node markdown-mcp-gemini.js

Using with Multiple AI Clients

You can use the same markdown-mcp server with multiple AI clients simultaneously. The MCP server is designed to handle multiple concurrent requests efficiently.

Benefits of Multi-Client Setup

Flexibility: Use the same tool with different AI models
Efficiency: Share the same server instance across clients
Consistency: Get the same extraction quality regardless of the AI client
Resource optimization: No need to run multiple server instances

Setup for Multiple Clients

Set up Claude Desktop using markdown-mcp.js (as described above)
Set up Gemini CLI using markdown-mcp-gemini.js (as described above)
Both clients can use their respective server files - optimized for each client

Usage Examples

With Claude Desktop:

Use markdown-mcp to extract content from https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html

With Gemini CLI:

# Extract and save to file gemini "Use get_page_markdown to extract content from https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html and save as result.md" # Or just extract without saving gemini "Use get_page_markdown to extract content from https://docs.confluent.io/cloud/current/flink/operate-and-deploy/monitor-statements.html"

Performance Considerations

The server handles multiple concurrent requests efficiently
Each request uses a fresh browser context for security
Memory usage scales with the number of concurrent requests
Typical response time: 5-15 seconds per request

Testing

The server has been tested and verified to work correctly with various websites including:

✅ Documentation sites (Confluent, GitHub, etc.)
✅ News articles and blog posts
✅ Technical documentation with code examples
✅ E-commerce pages and product descriptions
✅ JavaScript-heavy sites with dynamic content

Tested Features

✅ Extracts headings, paragraphs, and text content
✅ Preserves bold and italic formatting
✅ Handles code blocks and inline code
✅ Processes lists (ordered and unordered)
✅ Extracts tables with proper formatting
✅ Filters out navigation and footer content
✅ Handles images and links (when enabled)
✅ Responds to MCP protocol requests
✅ Works with dynamic content and JavaScript-heavy sites

Manual Testing

You can test the server manually by running:

# Test with a simple URL node -e " const { spawn } = require('child_process'); const server = spawn('node', ['markdown-mcp.js'], { stdio: ['pipe', 'pipe', 'pipe'] }); const request = { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'get_page_markdown', arguments: { url: 'https://example.com' } } }; server.stdin.write(JSON.stringify(request) + '\n'); setTimeout(() => { server.kill(); console.log('Test completed'); }, 10000); "

Supported Websites

This MCP server works well with:

Documentation sites: Confluent, GitHub, GitLab, etc.
News and blogs: Most major news sites and blogs
Technical content: Stack Overflow, Medium, Dev.to
E-commerce: Product pages and descriptions
Academic content: Research papers and articles
Social media: Twitter threads, LinkedIn articles

Performance

Typical extraction time: 5-15 seconds depending on page complexity
Memory usage: ~50-100MB per extraction
Supported content size: Up to several MB of text content
Concurrent requests: Handles multiple requests efficiently

Requirements

Node.js: Version 18 or higher
Playwright: Chromium browser (installed automatically)
Memory: At least 512MB available RAM
Disk space: ~200MB for Playwright browser

Security Considerations

The server runs in headless mode for security
No cookies or persistent data is stored
Each request uses a fresh browser context
Network requests are limited by timeout settings
No sensitive data is logged or stored

Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

Support

If you encounter issues:

Check the troubleshooting section above
Verify all requirements are met
Test with a simple URL first
Check Claude Desktop logs for error messages
Open an issue with detailed error information