talordata-mcp

Overview

talordata-mcp is an MCP server for Talor SERP.

It exposes:

• A primary search tool for live SERP requests
• Supporting history and statistics tools
• A list_engines tool for discovery
• Engine schema resources under talor://engines and talor://engines/<engine>

The server reuses the parameter definitions from engines/*.json in this repository and follows the serialization behavior used by the talor-webui-dashboard playground.

Quick Start

Run locally

git clone https://github.com/Talordata/talordata-mcp
cd talordata-mcp

go mod tidy
go run .

By default, configuration is loaded from configs/config.yaml.

The sample config in this repository is:

root_dir: .
listen_addr: ":8800"
upstream_endpoint: "https://serpapi.talordata.net/serp/v1/request"
history_endpoint: "https://api.talordata.com/accounts/v1/serp/mcp/history"
statistics_endpoint: "https://api.talordata.com/pay_package_view/v1/serp/mcp/statistics"
timeout_ms: 150000
shutdown_timeout_ms: 10000
log_prefix: "[talordata-mcp]"

After startup, the server exposes:

• GET /
• GET /healthz
• POST | GET | DELETE /mcp
• POST | GET | DELETE /{user-token}/mcp

Compile only

go build ./...

Example MCP client config

Recommended remote HTTP MCP setup:

{
  "mcpServers": {
    "talordata": {
      "url": "https://your-domain.com:8800/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_USER_TOKEN"
      }
    }
  }
}

For clients that cannot send custom headers:

{
  "mcpServers": {
    "talordata": {
      "url": "https://your-domain.com:8800/YOUR_USER_TOKEN/mcp"
    }
  }
}

Features

• Dynamically loads all engine schemas from local engines/*.json
• Exposes engine index and raw engine schemas through MCP resources
• Proxies Talor SERP search requests through the search tool
• Proxies usage history through the history tool
• Proxies usage statistics through the statistics tool
• Supports response format control via upstream json
• Supports schema-aware parameter serialization rules
• Supports per-request user token forwarding instead of storing a fixed upstream token

Supported serialization behavior

• date_range
• tags
• cr
• switch
• time_range
• cascader
• number
• google_flights airport code normalization

Response format mapping

• json=1 → structured JSON only
• json=2 → JSON + HTML
• json=3 → HTML only

Runtime Model

• Designed for cloud deployment with streamable-http
• The server does not persist a shared upstream token
• Each user provides their own Talor SERP token per MCP request
• The server authenticates the incoming request and forwards the user token upstream

Authentication

User token

Supported token delivery methods:

• Recommended: Authorization: Bearer <user-token>
• Compatible: X-Talor-Serp-Token: <user-token>
• Compatible: /{user-token}/mcp

Notes

• For /mcp, sending the token in headers is recommended
• /{user-token}/mcp is useful for clients that cannot customize headers
• Query string token passing is intentionally not supported
• The server does not infer agent-platform from inbound requests

Configuration

Service configuration is loaded from configs/config.yaml.

Fields

Tools

Business tools are implemented under the tools directory:

• tools/search.go
• tools/history.go
• tools/statistics.go

list_engines

Returns:

• Default engine
• Category list
• Engine list
• Schema resource URI for each engine

search

Executes a Talor SERP search request.

Parameters

Recommended flow

1. Read talor://engines
2. Read talor://engines/<engine>
3. Build params according to the schema
4. Call search

history

Queries Talor SERP usage history.

Parameters

statistics

Queries Talor SERP usage statistics.

Parameters

Resources

Parameter Serialization Rules

When building upstream form parameters:

• engine must be set to the engine key
• json must be included when needed by the upstream endpoint
• date_range fields are expanded to {field}_start and {field}_end
• tags values are joined with commas
• switch values are serialized as "true" / "false"
• cascader uses the last selected value
• number values are serialized as strings
• time_range values are formatted as HHmm,HHmm

Project Structure

Development

Local checks

go build ./...

Health endpoints

• GET / returns service metadata
• GET /healthz returns health status

Notes

• The implementation is inspired by serpapi/serpapi-mcp
• The project reuses local engine schema definitions from engines/*.json
• Platform identification depends on the inbound User-Agent when it matches a known client rule

🎁 Get Started for Free

Try TalorData SERP API with 1,000 free searches and start building AI agents, SEO tools, and search-driven applications today.

• No infrastructure to manage
• Multi-engine search access
• Real-time structured results
• Developer-friendly integration

👉 Start Free

🤝 Connect With Us

Have questions or want to collaborate? Reach out through any of the following channels:

• 📧 Email: support@talordata.com
• 🌐 Website: https://talordata.com
• 📱 WhatsApp: +852 5628 3471
• 💼 LinkedIn: TalorData

TalorData empowers developers and AI agents with fast, reliable search-data access through a single multi-engine SERP API.