Shellserver - MCP Article Retrieval Server

A simple Model Context Protocol (MCP) server that exposes a tool to retrieve blog articles from an external API.

Overview

This MCP server provides a single tool called get_articles that fetches and returns a list of blog articles with metadata including titles, authors, URLs, and engagement metrics.

Features

• Article Retrieval Tool: Fetches articles

• Structured Output: Returns validated data using Pydantic models

• Async HTTP: Uses httpx for efficient async API calls

• Error Handling: Proper exception handling for network and HTTP errors

Requirements

• Python 3.11 or higher

• uv (package manager)

Installation

1. Clone this repository

2. Install dependencies:

3. Create a .env file in the project root with the required API URL:

Usage

Running the Server

Start the MCP server:

The server uses stdio transport for communication with MCP clients.

Testing with MCP Inspector

The MCP Inspector is a web-based tool for testing MCP servers:

This will start the inspector and connect it to your server automatically.

Integration with Claude Desktop

To use this server with Claude Desktop, add it to your Claude Desktop configuration:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%/Claude/claude_desktop_config.json

Restart Claude Desktop after updating the configuration.

Available Tools

get_articles

Retrieves a list of blog articles from the API.

Parameters: None

Returns: A list of Article objects with the following fields:

• id (int): Unique article identifier

• title (str): Article title

• subtitle (str): Article subtitle

• image (str): URL to article image

• url (str): URL to article page

• author (str): Article author name

• time (str): Publication timestamp (ISO 8601)

• readtime (str): Estimated reading time

• category (int): Article category ID

• description (str): Article description

• shareCount (int): Number of shares

• checkCount (int): Number of views/checks

Example usage in Claude:

Project Structure

Dependencies

• mcp[cli]>=1.22.0 - Model Context Protocol SDK with CLI support

• httpx>=0.28.0 - Modern async HTTP client

• python-dotenv - Environment variable management from .env files

Development

Architecture

The server uses the FastMCP framework from the MCP Python SDK, which provides:

• Simple decorator-based tool registration

• Automatic JSON schema generation from type hints

• Built-in validation using Pydantic models

• Support for async operations

Code Structure

1. Pydantic Model: Defines the Article schema for type-safe data validation

2. Tool Function: The get_articles() async function fetches and validates article data

3. Server Instance: FastMCP server configured with streamable-http transport

Error Handling

The server includes comprehensive error handling for:

• HTTP errors (4xx, 5xx responses)

• Network connectivity issues

• JSON parsing errors

• Data validation failures

All errors are caught and returned as descriptive exception messages.

License

This project is provided as-is for educational and development purposes.

Resources

• MCP Documentation

• MCP Python SDK

• FastMCP Guide