convez.ai
MCP ServerIntegração & APIsAvançado
Talordata

Talor SERP MCP Server

Talordata/talordata-mcp

Servidor MCP para buscas SERP com engines dinâmicos e estadísticas

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que expõe acesso a buscas SERP via Talor Data, com suporte a histórico, estatísticas e múltiplos engines. Implementado em Go com arquitetura cloud-native e autenticação por token de usuário, ideal para integração em clientes MCP.

Instalação

$npx convez-ai Talordata/talordata-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
25%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integrar busca SERP em agentes Claude via MCP
  • Consultar histórico e estatísticas de uso de buscas
  • Descobrir e configurar múltiplos engines de busca dinamicamente

Veredito

Ferramenta especializada para quem precisa de integração SERP via MCP em produção. Requer infraestrutura cloud e token de autenticação Talor, com suporte robusto a streaming HTTP e múltiplos formatos de resposta.

README

A tradução para o português deste README ainda está na fila.

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

FieldDescription
root_dirProject root directory; supports relative paths and must contain engines/index.json
listen_addrService listen address
upstream_endpointTalor SERP search endpoint
history_endpointTalor SERP history endpoint
statistics_endpointTalor SERP statistics endpoint
timeout_msUpstream timeout in milliseconds
shutdown_timeout_msGraceful shutdown timeout in milliseconds
log_prefixLog prefix used by the service

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

ParameterRequiredDescription
engineNoEngine key such as google_web, google_images, bing_images
qNoSearch query
jsonNoResponse format: 1, 2, or 3
paramsNoEngine-specific parameters
response_modeNocomplete or compact

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

ParameterRequiredDescription
pageNoPage number, default 1
page_sizeNoPage size, commonly 20, 50, 100
search_queryNoSearch query filter
search_engineNoSearch engine filter
statusNoall, success, or error
start_timeNoStart time in Unix seconds
end_timeNoEnd time in Unix seconds
timezoneNoForwarded as X-Time-Zone

statistics

Queries Talor SERP usage statistics.

Parameters

ParameterRequiredDescription
start_dateYesStart date in YYYY-MM-DD
end_dateYesEnd date in YYYY-MM-DD
enginesNoComma-separated string or string array
timezoneNoTimezone offset such as +08:00

Resources

ResourceDescription
talor://enginesEngine index
talor://engines/<engine>Raw schema loaded from engines/<engine>.json

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

PathResponsibility
main.goService startup, MCP registration, HTTP routing, graceful shutdown
tools/search.gosearch tool definition and handler
tools/history.gohistory tool definition and handler
tools/statistics.gostatistics tool definition and handler
internal/auth/auth.goToken extraction, auth middleware, MCP context injection
internal/engines/registry.goEngine index and schema loading
internal/serp/client.goUpstream HTTP requests
internal/serp/serialize.goParameter serialization logic

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:


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

Ver o original no GitHub

Bom para

Relacionados