Defuddle MCP Server

A thin MCP wrapper around the Obsidian team's Defuddle tool. It fetches a webpage and returns clean, structured Markdown with metadata (title, author, publish date, description, domain, word count).

What it does

• Exposes one MCP tool: webpage_to_markdown

• Converts webpages into focused Markdown, stripping ads, navigation, and other clutter.

• Returns both plain Markdown text and structured metadata.

• Requires Bearer-token authorization on every HTTP endpoint.

Related MCP server: intercept-mcp

Endpoints

Default listening port is 3000 inside the container. The included docker-compose.yml exposes it on host port 3007.

Quick start

With Docker Compose

1. Copy the example environment file and set a real token:

   cp .env.example .env
   # edit .env
   # DEFUDDLE_MCP_TOKEN=your-secret-bearer-token

2. Build and run:

   docker compose up --build -d

3. The server is now available at http://localhost:3007/mcp.

Locally with Node.js

1. Install dependencies and build:

   npm install
   npm run build

2. Set the required token:

   export DEFUDDLE_MCP_TOKEN=your-secret-bearer-token
   # optional: export PORT=4000

3. Start the server:

   npm start

Configuration

To use a custom port, set both PORT and adjust the Docker Compose port mapping, e.g.:

ports:
  - "4000:4000"

Connect an MCP client

Add a server config like this (example for a client that supports streamable HTTP):

{
  "mcpServers": {
    "defuddle": {
      "url": "http://localhost:3007/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-bearer-token"
      }
    }
  }
}

Development

• npm run dev — run directly from TypeScript.

• npm run build — compile to dist/.