media-cloud-mcp

An MCP server for Media Cloud, the open archive of online news used for media research. It lets an AI assistant measure how much attention news media pay to a topic, compare sources and countries, examine the language of coverage, and find story URLs.

This is an independent project, not an official Media Cloud product. It is built on the official mediacloud Python client.

Setup

You need a Media Cloud API key. Sign in to Media Cloud, click the person icon at the top right, choose Profile, and copy your API key.

The server runs over stdio. With uv installed, add this to your MCP client's configuration, such as claude_desktop_config.json:

{
  "mcpServers": {
    "media-cloud": {
      "command": "uvx",
      "args": ["media-cloud-mcp"],
      "env": { "MC_API_KEY": "your-api-key" }
    }
  }
}

For Claude Code:

claude mcp add media-cloud --env MC_API_KEY=your-api-key -- uvx media-cloud-mcp

Or install it with pip install media-cloud-mcp and use media-cloud-mcp as the command. Python 3.11 or newer is required.

To confirm it works, ask your assistant to run the check_connection tool.

Tools

All tools are read-only.

The mediacloud://query-guide resource documents the query syntax. The server also sends it to the assistant as part of its instructions.

Example prompts

• "How much did US national media cover climate change in November 2023 compared with Indian national media?"
• "Which Nigerian news sources wrote the most about fuel subsidies last year?"
• "Chart the weekly share of stories about 'artificial intelligence' in the Washington Post in 2024."
• "What words most often appear in coverage of the housing crisis in Boston Globe stories?"

Limits

• Story text: Media Cloud returns metadata and URLs. Copyright restrictions keep full text limited to accounts with elevated access.
• Rate limit and quota: requests are rate limited per account, and the client library waits when it reaches the limit, so a burst of calls can be slow. Your account also has a weekly quota. Contact Media Cloud if you need more.

Development

uv sync
uv run pytest
uv run ruff check .

Tests replace only the HTTP layer and don't need an API key. To try the server interactively:

MC_API_KEY=your-api-key uv run media-cloud-mcp

Releasing

Update __version__ in src/media_cloud_mcp/__init__.py, then build and publish:

rm -rf dist && uv build

uv publish --token "$PYPI_TOKEN"

License

MIT