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.

Endpoints

Endpoint	Method	Auth	Purpose
/mcp	POST	Bearer token	MCP tool calls
/health	GET	Bearer token	Health check

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

Variable	Default	Description
DEFUDDLE_MCP_TOKEN	(required)	Bearer token clients must send as Authorization: Bearer <token>
PORT	3000	Port the server listens on inside the container

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/.