Skip to main content
Glama
Sign In
Skeleton MCP Server

Skeleton MCP Server

by nickweedon
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Skeleton MCP Server

A template project for building Model Context Protocol (MCP) servers. This skeleton provides a solid foundation with best practices, Docker support, and example implementations.

Features

  • FastMCP framework for easy MCP server development

  • Docker and Docker Compose support for containerized deployment

  • VS Code Dev Container configuration for consistent development environments

  • Example CRUD API implementation to demonstrate patterns

  • Test suite with pytest

  • Claude Code integration with custom commands

Related MCP server: MCP Server Template

Quick Start

Prerequisites

  • Python 3.10 or higher

  • uv package manager (recommended)

  • Docker (optional, for containerized deployment)

Installation

  1. Clone this repository and rename it for your project:

git clone <this-repo> my-mcp-server
cd my-mcp-server

  1. Rename the package:

    • Rename src/skeleton_mcp to src/your_project_name

    • Update pyproject.toml with your project name and metadata

    • Update imports in all Python files

  2. Install dependencies:

uv sync

  1. Create your environment file:

cp .env.example .env
# Edit .env with your API credentials

  1. Run the server:

uv run skeleton-mcp

Project Structure

skeleton_mcp/
├── src/skeleton_mcp/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # Main MCP server entry point
│   ├── client.py            # API client for backend communication
│   ├── types.py             # TypedDict definitions
│   ├── api/                  # API modules
│   │   ├── __init__.py
│   │   └── example.py       # Example CRUD operations
│   └── utils/               # Utility modules
│       └── __init__.py
├── tests/                   # Test suite
│   ├── conftest.py          # Pytest fixtures
│   ├── test_example_api.py  # API tests
│   └── test_server.py       # Server tests
├── docs/                    # Documentation
├── .claude/                 # Claude Code configuration
│   ├── commands/            # Custom slash commands
│   └── settings.local.json  # Permission settings
├── .devcontainer/           # VS Code dev container
├── Dockerfile               # Container image definition
├── docker-compose.yml       # Production compose file
├── docker-compose.devcontainer.yml  # Dev container compose
├── pyproject.toml           # Project configuration
├── CLAUDE.md               # Claude context documentation
└── README.md               # This file

Development

Running Tests

uv run pytest -v

Linting

uv run ruff check src/ tests/
uv run ruff format src/ tests/

Building

uv build

Adding Your Own Tools

  1. Create a new module in src/skeleton_mcp/api/:

# src/skeleton_mcp/api/my_api.py

async def my_tool(param1: str, param2: int = 10) -> dict:
    """
    Description of what this tool does.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value
    """
    # Your implementation here
    return {"result": "success"}

  1. Register the tool in server.py:

from .api import my_api

mcp.tool()(my_api.my_tool)

  1. Add types in types.py if needed:

class MyDataType(TypedDict):
    field1: str
    field2: int

Handling Large Files and Binary Data

For MCP servers that need to handle large file uploads, downloads, or binary blob storage, use the mcp-mapped-resource-lib library:

pip install mcp-mapped-resource-lib

This library provides:

  • Blob management with unique identifiers

  • Automatic TTL-based expiration and cleanup

  • Content deduplication

  • Security features (path traversal prevention, MIME validation)

  • Docker volume integration for shared storage

See CLAUDE.md for detailed usage examples.

Docker Deployment

Build and run with Docker Compose:

docker compose up --build

For development with VS Code Dev Containers:

  1. Open the project in VS Code

  2. Install the "Dev Containers" extension

  3. Click "Reopen in Container" when prompted

Claude Desktop Integration

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "skeleton-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/path/to/your/.env",
        "skeleton-mcp:latest"
      ]
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "skeleton-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/skeleton_mcp", "run", "skeleton-mcp"]
    }
  }
}

Available Tools

Tool

Description

health_check

Check server health and configuration status

list_items

List all items with filtering and pagination

get_item

Get a specific item by ID

create_item

Create a new item

update_item

Update an existing item

delete_item

Delete an item

Environment Variables

Variable

Description

Default

API_KEY

Your API key for authentication

(required)

API_BASE_URL

Base URL for the backend API

https://api.example.com/v1

API_TIMEOUT

Request timeout in seconds

30

DEBUG

Enable debug logging

false

License

MIT License - See LICENSE file for details.

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Run tests and linting

  5. Submit a pull request

Available Tools

6 tools
create_itemB

Create a new item.

Args: name: The name of the item (required) description: Optional description metadata: Optional key-value metadata

Returns: The created item data including the generated ID

Inputs: name (required), description, metadata. Returns: object

delete_itemC

Delete an item.

Args: item_id: The unique identifier of the item to delete

Returns: A confirmation message

Raises: ValueError: If the item is not found

Inputs: item_id (required). Returns: object

get_itemA

Get a specific item by ID.

Args: item_id: The unique identifier of the item

Returns: The item data if found

Raises: ValueError: If the item is not found

Inputs: item_id (required). Returns: object

health_checkB

Check the health status of the MCP server.

Returns: A dictionary with the server status and configuration info.

Inputs: no named parameters. Returns: object

list_itemsA

List all items with optional filtering and pagination.

Args: page: Page number (1-indexed) page_size: Number of items per page filter_name: Optional filter by name (case-insensitive contains)

Returns: A dictionary containing: - items: List of item objects - total: Total number of items matching the filter - page: Current page number - page_size: Number of items per page

Inputs: page, page_size, filter_name. Returns: object

update_itemB

Update an existing item.

Args: item_id: The unique identifier of the item to update name: New name (optional) description: New description (optional) metadata: New metadata (optional, replaces existing)

Returns: The updated item data

Raises: ValueError: If the item is not found

Inputs: item_id (required), name, description, metadata. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose with no ambiguity. The five item-related tools (create_item, delete_item, get_item, list_items, update_item) form a complete CRUD set for a single resource type, while health_check serves a completely different operational purpose. The descriptions reinforce these distinct roles, making tool selection straightforward.

    Naming Consistency5/5

    All tools follow a consistent verb_noun naming pattern with snake_case throughout. The item-related tools use standard CRUD verbs (create, delete, get, list, update) followed by the resource name 'item', while health_check maintains the same pattern. There are no deviations in style or convention across the toolset.

    Tool Count5/5

    Six tools is perfectly appropriate for this server's purpose. The five item management tools provide complete CRUD operations with pagination and filtering, while health_check adds necessary operational functionality. This is a well-scoped set where each tool clearly earns its place without being overwhelming or insufficient.

    Completeness5/5

    The tool surface provides complete coverage for the item management domain with full CRUD operations (create, read, update, delete) plus listing with filtering and pagination. The health_check tool adds operational monitoring. There are no obvious gaps - agents can perform all expected lifecycle operations on items without dead ends or workarounds.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • MCP Server Template

      rwxproject
      F
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive template for building Model Context Protocol servers with FastMCP framework, featuring modular architecture, auto-discovery registry, and support for multiple transport methods. Includes example arithmetic and weather tools to help developers quickly create custom MCP servers.
      -

    • Skeleton MCP Server

      nickweedon
      A
      license
      A
      quality
      D
      maintenance
      A template project for building Model Context Protocol servers with FastMCP framework, providing example CRUD API implementations, Docker support, and development best practices.
      6
      1
      MIT