jeromechoo/diffbot-mcp-by-claude

[!WARNING] This is a functional MCP server for Diffbot's Enhance API that comes with a side of a 5 year intern hot potato project tech debt. Everything after this alert was generated by Claude Sonnet 4. Learn more.

Diffbot MCP Server

A Model Context Protocol (MCP) server that provides access to Diffbot's DQL (Diffbot Query Language) and Enhance APIs.

Features

• DQL Search: Execute complex queries against Diffbot's Knowledge Graph
• URL Enhancement: Extract structured data from any URL using Diffbot's Enhance API
• Built-in Help: Get DQL syntax help and examples

Installation

1. Clone this repository
2. Install dependencies:

   pip install -r requirements.txt
   

3. Set up your Diffbot API token:

   export DIFFBOT_TOKEN=your_token_here
   

Usage

Running the Server

python diffbot_mcp_server.py

MCP Client Configuration

Add this to your MCP client configuration:

{
  "mcpServers": {
    "diffbot": {
      "command": "python",
      "args": ["/path/to/diffbot_mcp_server.py"],
      "env": {
        "DIFFBOT_TOKEN": "your_token_here"
      }
    }
  }
}

Available Tools

1. dql_search

Execute DQL queries against Diffbot's Knowledge Graph.

Parameters:

• query (required): DQL query string
• num (optional): Number of results (default: 10, max: 100)
• start (optional): Starting index for pagination (default: 0)

Example:

{
  "query": "type:article author:\"John Doe\" date:>2023-01-01",
  "num": 20
}

2. enhance_url

Extract structured data from URLs using Diffbot's Enhance API.

Parameters:

• url (required): URL to enhance
• fields (optional): Fields to extract (default: "meta,links,breadcrumb")

Example:

{
  "url": "https://example.com/article",
  "fields": "meta,links,breadcrumb,images"
}

3. dql_help

Get comprehensive help and examples for DQL syntax.

DQL Query Examples

# Find recent articles by specific author
type:article author:"Jane Smith" date:>2023-06-01

# Find tech products under $500
type:product tags:technology price:<500

# Find articles about AI from specific sites
type:article text:"artificial intelligence" (site:techcrunch.com OR site:wired.com)

# Complex query with multiple conditions
type:article author:"John Doe" date:2023-01-01..2023-12-31 NOT tags:opinion

Environment Variables

• DIFFBOT_TOKEN: Your Diffbot API token (required)

Error Handling

The server includes comprehensive error handling for:

• Invalid API tokens
• Network timeouts
• Malformed queries
• Rate limiting
• Invalid URLs

License

MIT License