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"
      }
    }
  }
}

3. 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}"

2. 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

3. 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