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:

uv sync

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

ALAYMAN_API_URL=your_api_url_here

Usage

Running the Server

Start the MCP server:

uv run server.py

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:

npx @modelcontextprotocol/inspector uv run server.py

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

{
  "mcpServers": {
    "shellserver": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/server.py"],
      "cwd": "/absolute/path/to/shellserver"
    }
  }
}

Restart Claude Desktop after updating the configuration.

Integration with Claude Code

You can add this server to Claude Code using the claude mcp add command. From the project directory, run:

claude mcp add --scope user alayman uv run $(pwd)/server.py

This will add the server with the name "alayman" to your user-level MCP configuration, making it available across all your Claude Code sessions.

Alternatively, you can manually add it to your Claude Code MCP configuration:

• macOS/Linux: ~/.claude/mcp.json
• Windows: %USERPROFILE%\.claude\mcp.json

{
  "mcpServers": {
    "shellserver": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/server.py"],
      "cwd": "/absolute/path/to/shellserver"
    }
  }
}

After updating the configuration, restart Claude Code or reload the MCP servers for the changes to take effect.

Integration with Docker and Claude Code

• Build the Docker image

docker build -t alayman .

• Add the Docker container as the MCP server

claude mcp add-json --scope user alayman '{"type":"stdio","command":"docker","args":["run","-i","--rm","--init","-e","DOCKER_CONTAINER=true","alayman"]}'

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:

Can you retrieve the latest articles using the get_articles tool?

Project Structure

shellserver/
   server.py           # Main MCP server implementation
   pyproject.toml      # Project dependencies
   README.md           # This file
   CLAUDE.md           # Claude Code project instructions
   .python-version     # Python version specification

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