Skip to main content
Glama
tim-akkio

MCP Server Framework

by tim-akkio
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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

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

Install Server
A
security – no known vulnerabilities
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tim-akkio/mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server