Fetch JSONPath MCP

Fetch JSONPath MCP

A Model Context Protocol (MCP) server that provides tools for fetching JSON data and web content from URLs. Features intelligent content extraction, multiple HTTP methods, and browser-like headers for reliable web scraping.

🎯 Why Use This?

Reduce LLM Token Usage & Hallucination - Instead of fetching entire JSON responses and wasting tokens, extract only the data you need.

Traditional Fetch vs JSONPath Extract

❌ Traditional fetch (wasteful):

✅ JSONPath extract (efficient):

Using pattern: data[*].name saves 99% tokens and eliminates model hallucination from irrelevant data.

Installation

For most IDEs, use the uvx tool to run the server.

Add this to your Windsurf MCP config file. See Windsurf MCP docs for more info.

Windsurf Local Server Connection

Development Setup

1. Install Dependencies

2. Start Demo Server (Optional)

3. Run MCP Server

Demo Server Data

The demo server at http://localhost:8080 returns:

Available Tools

fetch-json

Extract JSON data using JSONPath patterns with support for all HTTP methods.

Returns: [1, 2]

Parameters:

• url (required): Target URL
• pattern (optional): JSONPath pattern for data extraction
• method (optional): HTTP method (GET, POST, PUT, DELETE, etc.) - Default: "GET"
• data (optional): Request body for POST/PUT requests
• headers (optional): Additional HTTP headers

fetch-text

Fetch web content with intelligent text extraction. Defaults to Markdown format for better readability.

Returns: Clean text representation of the JSON data

Output Formats:

• "markdown" (default): Converts HTML to clean Markdown format
• "clean_text": Pure text with HTML tags removed
• "raw_html": Original HTML content

Parameters:

• url (required): Target URL
• method (optional): HTTP method - Default: "GET"
• data (optional): Request body for POST/PUT requests
• headers (optional): Additional HTTP headers
• output_format (optional): Output format - Default: "markdown"

batch-fetch-json

Process multiple URLs with different JSONPath patterns concurrently.

Returns: [{"url": "http://localhost:8080", "pattern": "foo[*].baz", "success": true, "content": [1, 2]}, {"url": "http://localhost:8080", "pattern": "bar.items[*]", "success": true, "content": [10, 20, 30]}]

Request Object Parameters:

• url (required): Target URL
• pattern (optional): JSONPath pattern
• method (optional): HTTP method - Default: "GET"
• data (optional): Request body
• headers (optional): Additional HTTP headers

batch-fetch-text

Fetch content from multiple URLs with intelligent text extraction.

Returns: [{"url": "http://localhost:8080", "success": true, "content": "# Demo Server Data\n\n..."}, {"url": "http://localhost:8080", "success": true, "content": "{\"foo\": [{\"baz\": 1, \"qux\": \"a\"}, {\"baz\": 2, \"qux\": \"b\"}]..."}]

Supports:

• Simple URL strings
• Full request objects with custom methods and headers
• Mixed input types in the same batch

JSONPath Examples

This project uses jsonpath-ng for JSONPath implementation.

For complete JSONPath syntax reference, see the jsonpath-ng documentation.

🚀 Performance Benefits

• Token Efficiency: Extract only needed data, not entire JSON responses
• Faster Processing: Smaller payloads = faster LLM responses
• Reduced Hallucination: Less irrelevant data = more accurate outputs
• Cost Savings: Fewer tokens = lower API costs
• Better Focus: Clean data helps models stay on task
• Smart Headers: Default browser headers prevent blocking and improve access
• Markdown Conversion: Clean, readable format that preserves structure

Configuration

Set environment variables to customize behavior:

Default Browser Headers: The server automatically includes realistic browser headers to prevent blocking:

• User-Agent: Chrome browser simulation
• Accept: Standard browser content types
• Accept-Language, Accept-Encoding: Browser defaults
• Security headers: Sec-Fetch-* headers for modern browsers

Custom headers in JSONRPC_MCP_HEADERS will override defaults when there are conflicts.

Development

What's New in v1.1.0

• ✨ Multi-Method HTTP Support: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
• 🔄 Tool Renaming: get-json → fetch-json, get-text → fetch-text
• 📄 Markdown Conversion: Default HTML to Markdown conversion with markdownify
• 🌐 Smart Browser Headers: Automatic browser simulation headers
• 🎛️ Format Control: Three output formats for text content (markdown, clean_text, raw_html)
• 🚀 Enhanced Batch Processing: Support for different methods in batch operations