Skip to main content
Glama
MCP Server Framework

MCP Server Framework

by tim-akkio

MCP Server Framework

A general-purpose Model Context Protocol (MCP) server that provides tools for Claude Code and Claude Desktop.

Quick Start

# Install dependencies
cd mcp-server
pip install -r requirements.txt

# Test the server runs (Ctrl+C to stop)
PYTHONPATH=src python -m mcp_server.server

Related MCP server: MCP Custom Tools Server

Project Structure

mcp-server/
├── src/mcp_server/
│   ├── server.py          # Main FastMCP server
│   ├── config.py          # Environment-based configuration
│   └── tools/
│       ├── __init__.py    # Tool registry
│       ├── echo_tool.py   # Example: basic echo tools
│       ├── datetime_tool.py  # Example: date/time utilities
│       └── file_tool.py   # Example: file operations
├── configs/               # Client configuration templates
└── requirements.txt

Configuration

The server is configured via environment variables:

Variable

Description

Default

MCP_SERVER_NAME

Display name for the server

mcp-server

MCP_LOG_LEVEL

Logging level (DEBUG, INFO, WARNING, ERROR)

INFO

MCP_ALLOWED_PATHS

Comma-separated paths for file tools

(none)

MCP_CUSTOM_VAR_*

Custom variables accessible via config

(none)

Included Tools

Echo Tools

  • echo - Echo back a message

  • echo_uppercase - Echo in uppercase

  • echo_reverse - Echo reversed

DateTime Tools

  • get_current_time - Get current UTC time

  • get_timestamp - Get current Unix timestamp

  • parse_timestamp - Convert timestamp to readable format

  • time_difference - Calculate time between two timestamps

File Tools (requires MCP_ALLOWED_PATHS)

  • list_directory - List directory contents

  • read_file - Read file contents

  • get_file_info - Get file/directory metadata

  • get_allowed_paths - Show configured allowed paths

Setting Up Clients

Claude Desktop

  1. Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

  2. Add your server configuration:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/full/path/to/mcp-server",
      "env": {
        "PYTHONPATH": "/full/path/to/mcp-server/src",
        "MCP_ALLOWED_PATHS": "/Users/you/Documents"
      }
    }
  }
}
  1. Restart Claude Desktop completely (Cmd+Q, then relaunch)

Claude Code

Create .mcp.json in your project root:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "${workspaceFolder}/mcp-server",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/mcp-server/src",
        "MCP_ALLOWED_PATHS": "${workspaceFolder}"
      }
    }
  }
}

Adding New Tools

  1. Create a new file in src/mcp_server/tools/:

# src/mcp_server/tools/my_tool.py
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from mcp.server.fastmcp import FastMCP
    from ..config import ServerConfig


def register(mcp: "FastMCP", config: "ServerConfig") -> None:
    """Register my tools with the server."""

    @mcp.tool()
    def my_function(param: str, count: int = 1) -> str:
        """
        Description shown to Claude.

        Args:
            param: What this parameter does
            count: Optional count with default

        Returns:
            What the tool returns
        """
        return f"Result: {param} x {count}"
  1. Register it in src/mcp_server/tools/__init__.py:

def register_all_tools(mcp: "FastMCP", config: "ServerConfig") -> None:
    from . import echo_tool, datetime_tool, file_tool, my_tool  # Add import

    echo_tool.register(mcp, config)
    datetime_tool.register(mcp, config)
    file_tool.register(mcp, config)
    my_tool.register(mcp, config)  # Add registration
  1. Restart Claude Desktop/Code to pick up the new tool.

Tool Design Guidelines

  1. Clear docstrings: The description and parameter docs are sent to Claude

  2. Type hints: All parameters and returns need type hints (defines the JSON schema)

  3. Return strings: Tools should return string results for best compatibility

  4. Error handling: Return user-friendly error messages rather than raising exceptions

  5. Use config: Access config for environment-specific settings (like allowed paths)

Troubleshooting

Server won't start:

  • Ensure PYTHONPATH includes the src directory

  • Check that mcp package is installed: pip install mcp[cli]

Tools not appearing in Claude:

  • Verify the config JSON is valid

  • Check the cwd path is correct

  • Restart Claude Desktop completely (Cmd+Q on Mac)

File tools return "not in allowed directories":

  • Set MCP_ALLOWED_PATHS to comma-separated directory paths

  • Paths must be absolute

Dependencies

  • Python 3.10+

  • mcp[cli]>=1.0.0

Available Tools

11 tools
echoB
    Echo back the provided message.

    Args:
        message: The message to echo back

    Returns:
        The same message, confirming receipt
    

Inputs: message (required). Returns: result

echo_reverseA
    Echo back the message reversed.

    Args:
        message: The message to reverse

    Returns:
        The message with characters in reverse order
    

Inputs: message (required). Returns: result

echo_uppercaseA
    Echo back the message in uppercase.

    Args:
        message: The message to transform and echo

    Returns:
        The message converted to uppercase
    

Inputs: message (required). Returns: result

get_allowed_pathsB
    Get the list of allowed file system paths.

    Returns:
        List of configured allowed paths or instructions to configure
    

Inputs: no named parameters. Returns: result

get_current_timeA
    Get the current date and time in UTC.

    Args:
        format: strftime format string (default: %Y-%m-%d %H:%M:%S)

    Returns:
        Formatted current date/time string in UTC
    

Inputs: format. Returns: result

get_file_infoA
    Get information about a file or directory.

    Requires MCP_ALLOWED_PATHS to be configured with permitted directories.

    Args:
        path: Path to get info about

    Returns:
        File information or error message
    

Inputs: path (required). Returns: result

get_timestampA
    Get the current Unix timestamp.

    Returns:
        Current time as Unix timestamp (seconds since epoch)
    

Inputs: no named parameters. Returns: result

list_directoryA
    List contents of a directory.

    Requires MCP_ALLOWED_PATHS to be configured with permitted directories.

    Args:
        path: Directory path to list

    Returns:
        Formatted directory listing or error message
    

Inputs: path (required). Returns: result

parse_timestampA
    Convert a Unix timestamp to a human-readable format.

    Args:
        timestamp: Unix timestamp (seconds since epoch)
        format: strftime format string

    Returns:
        Formatted date/time string in UTC
    

Inputs: timestamp (required), format. Returns: result

read_fileA
    Read contents of a text file.

    Requires MCP_ALLOWED_PATHS to be configured with permitted directories.

    Args:
        path: File path to read
        max_lines: Maximum number of lines to return (default: 100)

    Returns:
        File contents or error message
    

Inputs: path (required), max_lines. Returns: result

time_differenceB
    Calculate the difference between two timestamps.

    Args:
        start_timestamp: Start Unix timestamp
        end_timestamp: End Unix timestamp

    Returns:
        Human-readable time difference
    

Inputs: start_timestamp (required), end_timestamp (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some overlap between time-related tools. get_current_time, get_timestamp, and parse_timestamp all handle time data, which could cause confusion about which to use for specific scenarios. However, their descriptions clarify their differences: get_current_time returns formatted UTC, get_timestamp returns Unix seconds, and parse_timestamp converts Unix to formatted. The echo variants are clearly distinct in their transformations.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with clear verb_noun structures. Examples include echo_reverse, get_allowed_paths, list_directory, and parse_timestamp. There are no deviations in naming conventions, making the set predictable and easy to understand at a glance.

    Tool Count4/5

    With 11 tools, the count is reasonable for a framework server, but it feels slightly over-scoped due to redundancy. The three echo tools and multiple time tools could potentially be consolidated without losing functionality. However, the number is within the typical 3-15 range and covers basic utility operations adequately.

    Completeness3/5

    The server covers basic utility functions like echoing, time handling, and file operations, but there are notable gaps. For file operations, it provides get_file_info, list_directory, and read_file, but lacks write, delete, or update capabilities, which are common in file management. The time tools are comprehensive, but the overall domain of 'framework' is vague, making it hard to assess full coverage beyond these utilities.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that allows integration with Claude Desktop by creating and managing custom tools that can be executed through the MCP framework.
      -
    • A
      license
      B
      quality
      D
      maintenance
      A comprehensive MCP server with 30+ custom tools organized into categories: date/time operations, file management, system information, text processing, and web operations. Enables async communication with robust error handling and flexible CLI integration.
      31
      1
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      A comprehensive MCP server that provides AI assistants with tools for file system management, Git integration, and shell command execution. It features specialized code utilities for analysis, formatting, and linting to enhance development workflows within Claude Desktop.
      28
      7
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server built with the mcp-framework for developing and managing custom tools. It provides a structured foundation for building and integrating modular components like data processors and API clients into Claude Desktop.
      -