Build an MCP server in Python (tutorial)

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, not which business logic runs inside the server. Many teams never need a custom data collector. They need a thin server that forwards structured requests to an API they trust.

This tutorial focuses on Python because it matches most data and research stacks. It also draws a clear line. The steps below explain how to think about MCP in Python and how to fetch normalized trend series from Trends MCP over HTTPS. It does not replace the official MCP specification or every security edge case for production deployments.

For comparisons of MCP servers aimed at research workflows, start with best MCP servers for research and data analysis in 2026 and best MCP servers for trend research and content strategy.

What problem does an MCP server solve?

Large language models work with text. Real research tasks need tools: query APIs, read files, run SQL, pull time series. MCP standardizes how those tools register and how arguments pass back and forth. The server implements the tools. The client surfaces them to the model.

If the only missing piece is trend data, wiring a hosted MCP endpoint or REST API is often faster than building scrapers. That is where Trends MCP fits: it already normalizes sources such as Google Search, TikTok, YouTube, Reddit, Amazon, Wikipedia, and others into one contract.

When should a developer choose 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 config JSON. HTTP fits remote hosting and shared teams. The client connects to a URL with TLS and sends JSON-RPC style payloads.

Trends MCP publishes a hosted MCP endpoint over HTTP for clients that support it. Many readers will combine approaches: a local MCP server for internal tools, plus direct REST calls to https://api.trendsmcp.ai/api for batch jobs inside notebooks or Airflow.

What belongs in a minimal Python MCP server?

A minimal server parses MCP messages, dispatches to handlers, and returns structured content or errors. In production, add logging, timeouts, and secret management. For learning, focus on three ideas: tool definitions, argument validation, and stable JSON responses.

The official MCP SDKs evolve quickly. Rather than pinning code that may go stale, treat the official Model Context Protocol repositories as the source of truth for class names and message shapes. This article keeps the architecture explicit so the concepts survive library updates.

How can Python call Trends MCP without building collectors?

Trends MCP exposes a REST API at https://api.trendsmcp.ai/api. Authenticate with a bearer token. Send JSON that includes a source string and a keyword string. The API returns normalized series suitable for charts and downstream tables.

Example pattern:

import requests

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

Swap source and keyword to match the table in the public docs. TikTok uses tiktok and expects a hashtag or topic string. YouTube uses youtube. The exact strings are lowercase and must match the documentation.

Where does this connect to SEO and content workflows?

Once JSON is available inside Python, it can feed internal dashboards, slide decks, or content calendars. Teams that bridge trend pulls with editorial planning often pair API calls with editorial briefs. A practical bridge article is how to use trend data for SEO content in 2026.

What are the main mistakes to avoid?

Secrets in repositories are the most common failure. Keep API keys in environment variables or a secrets manager. The second failure is unbounded polling. Batch queries, cache responses, and respect rate limits. The third failure is mixing transport layers by accident, for example pointing an HTTP MCP client at a stdio-only binary without a wrapper.

What does a safe local development loop look like?

Start with a read-only script that prints the JSON shape for one source and keyword. Commit that script without secrets. Add unit tests around parsing and validation before adding retries. When the script is stable, wrap it behind an MCP tool handler so the model sees a narrow interface: one tool name, a short description, and typed arguments. That boundary keeps prompts from drifting into arbitrary code execution.

How should teams handle errors and partial failures?

HTTP APIs return status codes. Treat non-200 responses as structured events: log the status, log a redacted body snippet, and surface a clear message to the operator. For batch jobs, separate transient errors (timeouts) from permanent errors (bad source strings). Idempotent retries help for timeouts; they do not help when the keyword is invalid. Trends MCP documents valid source values in the public reference. Matching those strings exactly avoids an entire class of avoidable failures.

How does Trends MCP pricing show up in code?

Free tiers exist for experimentation. Paid tiers raise monthly request limits. Billing details belong in the product console, not hard-coded in scripts. Write functions that read the key from TRENDSMCP_API_KEY and fail fast when it is missing.

What if the team only needs reports, not chat?

Scheduled jobs can skip MCP entirely. A nightly Python task can call the REST API, write Parquet or CSV to object storage, and let BI tools read the files. MCP shines when humans ask new questions every day. Batch APIs shine when the questions repeat on a calendar. Many organizations run both: MCP for exploration, cron for steady metrics.

FAQ

Do I need a custom MCP server to use Trends MCP? No. Many users rely on the hosted MCP endpoint or REST API directly. Custom servers matter when internal policies require a proxy or extra policy checks.

Can this replace pytrends or custom Google Trends scrapers? That depends on the needed sources and compliance posture. Trends MCP covers many sources behind one API. For Google-only comparisons, see best Google Trends alternatives in 2026.

Is the REST snippet enough for production? It is a starting point. Add retries, backoff, structured logging, and monitoring before production traffic.