Simple MCP Servers

Repository for holding one-file MCP servers written in Python

Overview

This repository contains self-contained, single-file MCP (Model Context Protocol) servers that can be easily integrated into Claude Desktop or other MCP-compatible applications. Each server is designed to be standalone with dependencies declared using PEP 723 inline script metadata.

Features

• Self-contained scripts - Each MCP server is a single Python file with embedded dependencies
• PEP 723 compliant - Uses inline script metadata for dependency management
• Direct execution - Scripts can be run directly with uv or executed as standalone programs
• No setup required - Dependencies are automatically handled by uv at runtime

Available MCP Servers

1. deer_to_bsky.py

Converts deer.social URLs to Bluesky-compatible AT URI formats for seamless integration with Bluesky tools.

2. large_file_reader_mcp.py

Provides efficient methods for reading large files in chunks, including line-based reading, head/tail operations, byte-based access, and pattern searching with context.

3. time_god_mcp.py

A Scrabble word validation server containing the complete SOWPODS word list for word game applications.

Installation & Usage

Prerequisites

• Python >= 3.11
• uv package manager

Running a Server

Each server can be run in multiple ways:

Method 1: Direct execution (if executable)

./deer_to_bsky.py

Method 2: Using uv

uv run --script deer_to_bsky.py

Claude Desktop Configuration

Add any server to your Claude Desktop configuration:

{
  "mcpServers": {
    "deer-to-bsky": {
      "command": "/path/to/uv",
      "args": [
        "run",
        "--script",
        "/path/to/deer_to_bsky.py"
      ]
    }
  }
}

Development

Creating a New MCP Server

1. Start with the PEP 723 header:

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "fastmcp",
#     "pydantic"
# ]
# ///

2. Follow the existing pattern for structure and documentation
3. Make the file executable: chmod +x your_server_mcp.py

Dependencies

All servers use:

• fastmcp - MCP framework
• pydantic - Data validation

Dependencies are declared inline using PEP 723 format, eliminating the need for requirements.txt or other external dependency files.

Claude Instructions

See CLAUDE.md for detailed collaboration notes and development guidelines.

License

MIT License - See LICENSE file for details

Author

Joshua Shew (2025)