How to Turn Any REST API Into an MCP Server for Claude (Complete 2026 Pillar Guide)

				
					"""mediastack MCP server."""
import os
from typing import Any

import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("mediastack")
MEDIASTACK_BASE = "https://api.mediastack.com/v1"
API_KEY = os.environ.get("MEDIASTACK_API_KEY")


async def mediastack_get(path: str, params: dict[str, Any]) -> dict[str, Any]:
    """Shared helper: attach access_key, call the API, return clean JSON."""
    if not API_KEY:
        return {"error": "MEDIASTACK_API_KEY environment variable is not set."}

    params = {**params, "access_key": API_KEY}
    url = f"{MEDIASTACK_BASE}/{path}"

    async with httpx.AsyncClient(timeout=30.0) as client:
        try:
            response = await client.get(url, params=params)
            response.raise_for_status()
            data = response.json()
        except httpx.HTTPStatusError as exc:
            return {"error": f"HTTP {exc.response.status_code}",
                    "detail": exc.response.text[:500]}
        except httpx.HTTPError as exc:
            return {"error": "Network error", "detail": str(exc)}

    if isinstance(data, dict) and "error" in data:
        err = data["error"]
        return {"error": err.get("code", "api_error"),
                "detail": err.get("message", "")}
    return data


@mcp.tool()
async def search_news(
    keywords: str,
    countries: str = "",
    categories: str = "",
    languages: str = "en",
    limit: int = 10,
) -> dict[str, Any]:
    """Search live news articles from mediastack.

    Use this when the user asks for recent news, headlines, or articles
    on a specific topic. Results include title, author, description,
    source, URL, and publication timestamp.

    Args:
        keywords: Search terms. Prefix with '-' to exclude (e.g. "tesla -musk").
        countries: Comma-separated 2-letter country codes (e.g. "us,gb,de").
        categories: One of general, business, entertainment, health,
            science, sports, technology.
        languages: Comma-separated 2-letter language codes. Defaults to "en".
        limit: Number of articles (1-100). Defaults to 10.
    """
    params: dict[str, Any] = {
        "keywords": keywords,
        "languages": languages,
        "limit": max(1, min(limit, 100)),
        "sort": "published_desc",
    }
    if countries:
        params["countries"] = countries
    if categories:
        params["categories"] = categories
    return await mediastack_get("news", params)


@mcp.tool()
async def get_historical_news(
    date: str,
    keywords: str = "",
    countries: str = "",
    limit: int = 10,
) -> dict[str, Any]:
    """Fetch historical news from a specific date or range.

    Requires mediastack Standard plan or higher.

    Args:
        date: Single date "YYYY-MM-DD" or range "YYYY-MM-DD,YYYY-MM-DD".
        keywords: Optional search terms.
        countries: Optional comma-separated country codes.
        limit: 1-100. Defaults to 10.
    """
    params: dict[str, Any] = {"date": date, "limit": max(1, min(limit, 100))}
    if keywords:
        params["keywords"] = keywords
    if countries:
        params["countries"] = countries
    return await mediastack_get("news", params)


@mcp.tool()
async def list_news_sources(
    search: str,
    countries: str = "",
    categories: str = "",
    limit: int = 25,
) -> dict[str, Any]:
    """Find news sources supported by mediastack.

    Use this when the user wants to know which publications are available
    or needs a source ID to filter later searches.
    """
    params: dict[str, Any] = {"search": search, "limit": max(1, min(limit, 100))}
    if countries:
        params["countries"] = countries
    if categories:
        params["categories"] = categories
    return await mediastack_get("sources", params)


if __name__ == "__main__":
    mcp.run(transport="stdio")