Provides persistence layer for storing news articles and metadata using Supabase.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@news-mcp search for recent news about quantum computing"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Agentic NewsAPI.org MCP server with semantic search, article versioning, ChromaDB retrieval, and Supabase persistence
Built with FastMCP and mcp-refcache for efficient handling of large data in AI agent tools.
✅ Reference-Based Caching - Return references instead of large data, reducing context window usage
✅ Preview Generation - Automatic previews for large results (sample, truncate, paginate strategies)
✅ Pagination - Navigate large datasets without loading everything at once
✅ Access Control - Separate user and agent permissions for sensitive data
✅ Private Computation - Let agents compute with values they cannot see
✅ Docker Ready - Production-ready containers with Python slim base image
✅ GitHub Actions - CI/CD with PyPI publishing and GHCR containers
✅ Langfuse Tracing - Built-in observability integration
✅ Type-Safe - Full type hints with Pydantic models
✅ Testing Ready - pytest with 73% coverage requirement
✅ Pre-commit Hooks - Ruff formatting and linting
Related MCP server: newsapi-mcp
Python 3.12+
uv (recommended) or pip
# Clone the repository
git clone https://github.com/l4b4r4b4b4/news-mcp
cd news-mcp
# Install dependencies
uv sync
# Run the server (stdio mode for Claude Desktop)
uv run news-mcp
# Run the server (SSE/HTTP mode for deployment)
uv run news-mcp --transport sse --port 8000# Run directly with uvx (no install needed)
uvx news-mcp stdio
# Or install globally
uv tool install news-mcp
news-mcp --help# Pull and run from GHCR
docker pull ghcr.io/l4b4r4b4b4/news-mcp:latest
docker run -p 8000:8000 ghcr.io/l4b4r4b4b4/news-mcp:latest
# Or build locally with Docker Compose
docker compose up
# Build images manually
docker compose --profile build build base
docker compose buildAdd to your claude_desktop_config.json:
{
"mcpServers": {
"news-mcp": {
"command": "uv",
"args": ["run", "news-mcp"],
"cwd": "/path/to/news-mcp"
}
}
}The project includes .zed/settings.json pre-configured for MCP context servers.
news-mcp/
├── app/ # Application code
│ ├── __init__.py # Version export
│ ├── server.py # Main server with tools
│ ├── tools/ # Tool modules
│ └── __main__.py # CLI entry point
├── tests/ # Test suite
│ ├── conftest.py # Pytest fixtures
│ └── test_server.py # Server tests
├── docker/
│ ├── Dockerfile.base # Python slim base image with dependencies
│ ├── Dockerfile # Production image (extends base)
│ └── Dockerfile.dev # Development with hot reload
├── .github/
│ └── workflows/
│ ├── ci.yml # CI pipeline (lint, test, security)
│ ├── publish.yml # PyPI trusted publisher
│ └── release.yml # Docker build & publish to GHCR
├── .agent/ # AI assistant workspace
│ └── goals/
│ └── 00-Template-Goal/ # Goal tracking template
├── pyproject.toml # Project config
├── docker-compose.yml # Local development & production
├── flake.nix # Nix dev shell
└── .rules # AI assistant guidelines# Install dependencies
uv sync
# Install pre-commit and pre-push hooks
uv run pre-commit install --install-hooks
uv run pre-commit install --hook-type pre-pushuv run pytest
uv run pytest --cov # With coverageuv run ruff check . --fix
uv run ruff format .uv run mypy app/# Run development container with hot reload
docker compose --profile dev up
# Build base image (for publishing)
docker compose --profile build build base
# Build all images
docker compose buildnix develop # Enter dev shell with all toolsVariable | Description | Default |
| Langfuse public key | - |
| Langfuse secret key | - |
| Langfuse host URL |
|
uvx news-mcp --help
Commands:
stdio Start server in stdio mode (for Claude Desktop and local CLI)
sse Start server in SSE mode (Server-Sent Events)
streamable-http Start server in streamable HTTP mode (recommended for remote/Docker)
# Examples:
uvx news-mcp stdio # Local CLI mode
uvx news-mcp sse --port 8000 # SSE on port 8000
uvx news-mcp streamable-http --host 0.0.0.0 # Docker/remote modeThis project uses a CI-gated workflow to ensure code quality and safe releases:
┌─────────────────────────────────────────────────────────────┐
│ Feature Branch → Open PR │
│ ↓ │
│ CI Runs (lint, test, security) │
│ ↓ │
│ ✅ CI Must Pass (enforced by branch protection) │
│ ↓ │
│ Merge to main │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ CI Re-runs on main │
│ ↓ │
│ Release Workflow waits for CI Success │
│ ↓ │
│ Docker Images Built & Pushed to GHCR │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Manually Create GitHub Release │
│ ↓ │
│ Publish Workflow verifies Release succeeded │
│ ↓ │
│ Package Published to PyPI │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ CD Workflow deploys (staging/production) │
└─────────────────────────────────────────────────────────────┘Key Safeguards:
✅ Branch protection ensures CI passes before merge
✅ Tag pushes verify CI passed before building images
✅ Publish workflow verifies Release succeeded before PyPI upload
✅ CD workflow only deploys after Release completes
Manual Gates:
🔒 Creating GitHub Release (allows review before PyPI publish)
🔒 Production deployments (requires manual approval)
Configure trusted publisher at PyPI:
Project name: news-mcp
Owner: l4b4r4b4b4
Repository: news-mcp
Workflow: publish.yml
Environment: pypi
Images are automatically published to GHCR on:
Push to main branch → latest tag
Version tags (v*.*.*) → latest, v0.0.1, 0.0.1, 0.0 tags
MIT License - see LICENSE for details.
See CONTRIBUTING.md for development guidelines.
mcp-refcache - Reference-based caching for MCP servers
FastMCP - High-performance MCP server framework
Model Context Protocol - The underlying protocol specification
This server cannot be deployed
The only News based AI MCP your agents will ever need — custom categories, global regions, and time-scoped results in one tool. We use multi-vector & sparse-hybrid search to search through thousands of articles across the world to find the exact news you're looking for.
Remote ChromaDB vector database MCP server with streamable HTTP transport
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
MCP server for interacting with the Supabase platform
