MCP Server Framework
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Server Framework list the files in the current directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.serverRelated 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.txtConfiguration
The server is configured via environment variables:
Variable | Description | Default |
| Display name for the server |
|
| Logging level (DEBUG, INFO, WARNING, ERROR) |
|
| Comma-separated paths for file tools | (none) |
| Custom variables accessible via config | (none) |
Included Tools
Echo Tools
echo- Echo back a messageecho_uppercase- Echo in uppercaseecho_reverse- Echo reversed
DateTime Tools
get_current_time- Get current UTC timeget_timestamp- Get current Unix timestampparse_timestamp- Convert timestamp to readable formattime_difference- Calculate time between two timestamps
File Tools (requires MCP_ALLOWED_PATHS)
list_directory- List directory contentsread_file- Read file contentsget_file_info- Get file/directory metadataget_allowed_paths- Show configured allowed paths
Setting Up Clients
Claude Desktop
Open
~/Library/Application Support/Claude/claude_desktop_config.json(macOS)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"
}
}
}
}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
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}"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 registrationRestart Claude Desktop/Code to pick up the new tool.
Tool Design Guidelines
Clear docstrings: The description and parameter docs are sent to Claude
Type hints: All parameters and returns need type hints (defines the JSON schema)
Return strings: Tools should return string results for best compatibility
Error handling: Return user-friendly error messages rather than raising exceptions
Use config: Access
configfor environment-specific settings (like allowed paths)
Troubleshooting
Server won't start:
Ensure
PYTHONPATHincludes thesrcdirectoryCheck that
mcppackage is installed:pip install mcp[cli]
Tools not appearing in Claude:
Verify the config JSON is valid
Check the
cwdpath is correctRestart Claude Desktop completely (Cmd+Q on Mac)
File tools return "not in allowed directories":
Set
MCP_ALLOWED_PATHSto comma-separated directory pathsPaths must be absolute
Dependencies
Python 3.10+
mcp[cli]>=1.0.0
Available Tools
11 toolsechoB
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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that allows integration with Claude Desktop by creating and managing custom tools that can be executed through the MCP framework.-
- AlicenseBqualityDmaintenanceA 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.311MIT
- AlicenseCqualityDmaintenanceA 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.287MIT
- FlicenseNot gradedqualityDmaintenanceA 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.-