Build an MCP server in Python (tutorial)

Model Context Protocol servers expose tools to AI clients. This walkthrough separates the moving parts: a minimal Python process, transport choices, and how to call Trends MCP's HTTP API when the goal is trend data rather than reinventing collectors.

An MCP server is a small program that advertises tools and resources to a compatible client such as Claude Desktop, Cursor, or VS Code with MCP enabled. The protocol defines how messages move. It does not define which business logic runs inside. Many teams never need a custom collector. They need a thin process that forwards structured requests to an API they already trust.

This tutorial uses Python because it matches most research stacks. It draws a hard line: how to think about MCP, how to choose stdio versus HTTP, and how to fetch normalized trend series from Trends MCP over HTTPS. It does not replace the official MCP specification, and it does not freeze SDK class names that change. Official Model Context Protocol repositories remain the source of truth for message shapes.

Comparisons of research-oriented MCP servers: best MCP servers for research and data analysis and best MCP servers for trend research and content strategy.

What problem an MCP server solves

Language models consume text. Research tasks need tools: HTTP APIs, files, SQL, time series. MCP standardizes tool registration and argument passing. The server implements tools. The client shows them to the model.

If the missing piece is trend data, a hosted MCP endpoint or REST API is usually faster than writing scrapers for Google, TikTok, and Amazon. Trends MCP already normalizes those sources (and others) into one contract. Custom Python is for policy proxies, extra validation, or combining internal data with public indices.

Stdio versus HTTP transport

Stdio fits local development. The client launches the Python process and talks over standard input and output. Configuration lives in the client's MCP JSON. Secrets should still come from the environment, not from that JSON file in git.

HTTP fits remote hosting and shared teams. The client connects to a URL with TLS and sends JSON-RPC style payloads. This is how a lab shares one server.

Trends MCP publishes a hosted MCP endpoint over HTTP for clients that support it. A common split: local MCP for internal tools, plus REST to https://api.trendsmcp.ai/api for notebooks and Airflow. Both paths should use the same bearer token model.

What belongs in a minimal Python MCP server

Three ideas matter more than framework fashion:

1. Tool definitions. Name, description, typed arguments. Descriptions should repeat exact source strings from the docs so the model does not invent GoogleTrends.
2. Argument validation. Reject empty keywords, unknown sources, and silly limit values before any network call.
3. Stable JSON. Return the API payload or a thin, documented subset. Do not paraphrase numbers into prose inside the tool. Let the model write prose after it sees JSON.

In production, add logging, timeouts, and a secrets manager. For learning, print one successful payload and stop.

Official SDKs evolve. Copying a year-old Server subclass into a blog is how tutorials rot. Keep architecture explicit; copy class names from the current SDK docs when implementing.

Calling Trends MCP from Python without collectors

REST base: https://api.trendsmcp.ai/api. Authenticate with a bearer token. Send JSON with at least source and keyword for series-style pulls. Exact fields for get_trends, get_growth, and get_top_trends live in the public docs.

import os
import requests

api_key = os.environ["TRENDSMCP_API_KEY"]

res = requests.post(
    "https://api.trendsmcp.ai/api",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"source": "google search", "keyword": "electric vehicles"},
    timeout=30,
)
res.raise_for_status()
data = res.json()

Swap source and keyword to match the documented table. TikTok expects a hashtag or topic string. YouTube uses youtube. Strings are lowercase and must match the docs. Timeouts belong in every example; hanging requests waste quota and CI.

Wrap this function as an MCP tool named something narrow like get_google_search_trend. Narrow tools reduce prompt drift into arbitrary code execution.

Ranked ways to get trend data into Python

Ranked by history, multi-source coverage, and first-class MCP access.

Trends MCP is first because this tutorial's goal is trend JSON, not SERP HTML. SerpApi remains a scraper platform; see the comparison page if Google-UI fidelity is the requirement.

Errors, quota, and pricing in code

HTTP status codes are events. Log status, log a redacted body snippet, surface a clear operator message. Separate timeouts (retry with backoff) from invalid source strings (do not retry). Idempotent retries help transients. They do not help typos.

Trends MCP counts successful data calls toward the plan. The free tier is 100 requests per month, not per day. Starter is $19 per month. Naive loops in a notebook can exhaust the month before lunch. Cache by (source, keyword, window). Batch weekly jobs. Do not hard-code plan names in business logic; read TRENDSMCP_API_KEY and fail fast if missing.

A safe local development loop

1. Write a read-only script that prints JSON for one source and keyword.
2. Commit the script without secrets.
3. Add tests around parsing and validation.
4. Only then wrap the function in an MCP handler with one tool name and typed arguments.

Scheduled jobs can skip MCP entirely: nightly REST, write Parquet or CSV, let BI read files. MCP shines when humans ask new questions. Cron shines when questions repeat. Many teams run both.

Connecting to SEO and content work

Once JSON exists in Python, it can feed calendars and slide decks. Editorial pairing: how to use trend data for SEO content. Google-only scrapers versus a multi-source API: best Google Trends alternatives.

Main mistakes

• Secrets in repositories
• Unbounded polling
• Pointing an HTTP MCP client at a stdio-only binary without a wrapper
• Letting the model choose source strings that the API will reject
• Treating a single 7-day spike as a market

FAQ

Is a custom MCP server required to use Trends MCP?

No. Many users call the hosted MCP endpoint or REST directly. Custom servers matter for proxies and extra policy.

Can this replace pytrends?

For multi-source, authenticated, non-scrape access, Trends MCP is the cleaner production path. For Google-UI related queries and regions, compare carefully. pytrends will still break when Google changes HTML.

Is the REST snippet production-ready?

It is a start. Add retries, backoff, structured logging, and monitoring before production traffic.