This MCP server provides two tools for working with news data via the MCP protocol. The first tool, get-top-headline, retrieves the current top headlines by category such as business, entertainment, general, health, science, sports, or technology. The second tool, search-news-query, enables searching news articles using a query string with optional filters for date ranges and sort order. The server is implemented in Kotlin using Ktor and relies on the NewsAPI service, so you must provide a NewsAPI key in the NEWS_API_KEY environment variable for authentication. Once the server is running, you can invoke the MCP tools through your MCP client (like Cursor) to fetch headlines or perform targeted searches against NewsAPI data, receiving structured responses that align with the MCP data model.

Prerequisites:

• Java Development Kit (JDK) 11 or newer
• Gradle build system
• Access to NewsAPI.org and a valid API key

Installation and setup steps:

1. Clone the repository: git clone https://github.com/nishantpardamwar/kotlin-news-mcp-server.git cd kotlin-news-mcp-server

2. Obtain a NewsAPI key:

   • Register at https://newsapi.org/register and get your API key.
   • Set the environment variable NEWS_API_KEY to your key before running the server.

3. Build the project (local development): ./gradlew build

4. Run the server (local development): ./gradlew run

   The server will typically start on http://localhost:3001

5. (Optional) Run via Docker:

   • Ensure Docker is installed and running.
   • Build an image or use a prebuilt image if available for this MCP server.
   • Example (pull the image and run): docker pull nishantpardamwar/kotlin-news-mcp-server docker run -i -e NEWS_API_KEY=your_api_key_here -p 3001:3001 nishantpardamwar/kotlin-news-mcp-server

6. Verify the server is running:

   • Access http://localhost:3001 to confirm the MCP endpoint is available.

Note: If you customize the environment (for example, change the port), ensure your MCP client points to the correct URL and port.

Environment variables:

• NEWS_API_KEY: Your NewsAPI key is required for fetching headlines and search results. Ensure this is set in your runtime environment.

Common issues:

• If the server fails to start due to port conflicts, stop the other service using the same port or configure the server to listen on a different port.
• If NewsAPI requests fail with authentication errors, double-check the NEWS_API_KEY value and ensure it is exported to the environment where the server runs.
• When running in Docker, remember to propagate the environment variable into the container (e.g., -e NEWS_API_KEY) and map the correct port.

Configuration options:

• The MCP endpoints expose two tools: get-top-headline and search-news-query. You can adjust client configurations to call these tools with the required inputs (category, query, fromDate, toDate, sortBy).

Troubleshooting tips:

• Check server logs for any Kotlin exceptions during startup or request handling.
• Verify network access to NewsAPI from the runtime environment.
• Ensure Gradle and JDK versions are compatible with the Kotlin codebase.