Custom MCP Server Project

A custom Model Context Protocol (MCP) server implementation with an interactive Python client. This project demonstrates how AI assistants can extend their capabilities by connecting to external tools and services.

What is MCP?

Model Context Protocol (MCP) is a standardized protocol that enables AI assistants to interact with external data sources and tools. It acts as a bridge between AI models and real-world applications, allowing AI to access live data and perform actions beyond their training data.

Features

MCP Server (server.py)

• Add Tool: Performs addition of two numbers
• Secret Word Tool: Returns a random secret word from a predefined list
• Weather Tool: Fetches real-time weather data for any city using the wttr.in API

Interactive Client (client.py)

• Menu-driven interface for easy tool selection
• Dynamic user input for all tool parameters
• Error handling and validation
• Unicode support for weather symbols
• Async/await architecture for efficient communication

Tech Stack

• Python 3.13
• FastMCP Framework: For creating MCP servers
• Asyncio: For asynchronous programming
• Requests: For HTTP API calls
• JSON-RPC: For client-server communication
• wttr.in API: For weather data

Project Structure

custommcp/
├── server.py          # MCP server with tool definitions
├── client.py          # Interactive client application
└── README.md          # Project documentation

Installation

Prerequisites

• Python 3.10 or higher
• pip (Python package manager)

Setup

1. Clone the repository:

git clone https://github.com/hemalathaa90/Custom_MCP_UsingPython.git
cd Custom_MCP_UsingPython

2. Install required dependencies:

pip install mcp requests

Usage

Running the Interactive Client

The easiest way to use the MCP server is through the interactive client:

python client.py

Interactive Menu:

==================================================
MCP Client - Interactive Mode
==================================================

Available tools:
  1. add: Add two numbers.
  2. get_secret_word: Get a random secret word
  3. get_current_weather: Get current weather for a city

Choose a tool to call (or 'q' to quit):
  1. add - Add two numbers
  2. get_secret_word - Get a random secret word
  3. get_current_weather - Get weather for a city
  q. Quit
==================================================

Enter your choice (1/2/3/q):

Example Usage

1. Adding Numbers:

Enter your choice (1/2/3/q): 1
Enter first number: 25
Enter second number: 17

Result: 25 + 17 = 42

2. Getting a Secret Word:

Enter your choice (1/2/3/q): 2

Secret word: banana

3. Getting Weather Data:

Enter your choice (1/2/3/q): 3
Enter city name: London

Fetching weather for London...
Weather report:
[Weather data for London]

Running the Server Standalone

If you want to run just the server (for integration with other MCP clients like Claude Desktop):

python server.py

Integration with Claude Desktop

To use this MCP server with Claude Desktop:

1. Locate your Claude Desktop config file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the server configuration:

{
  "mcpServers": {
    "demo-mcp-server": {
      "command": "python",
      "args": ["path/to/custommcp/server.py"]
    }
  }
}

3. Restart Claude Desktop

4. The tools will now be available in your Claude conversations!

API Reference

Tools

add(a: int, b: int) -> int

Adds two integers and returns the result.

Parameters:

• a (int): First number
• b (int): Second number

Returns:

• Sum of a and b

Example:

add(5, 3)  # Returns: 8

---

get_secret_word() -> str

Returns a random word from a predefined list.

Parameters: None

Returns:

• A random word (apple, banana, cherry, date, or elderberry)

Example:

get_secret_word()  # Returns: "banana"

---

get_current_weather(city: str) -> str

Fetches current weather information for a specified city.

Parameters:

• city (str): Name of the city

Returns:

• Weather report text from wttr.in

Example:

get_current_weather("London")  # Returns weather data for London

Technical Details

Architecture

The project uses a client-server architecture:

1. Server (server.py):

   • Runs as a subprocess when called by the client
   • Communicates via stdio (standard input/output)
   • Uses JSON-RPC protocol for message formatting
   • Implements MCP protocol for tool registration and execution

2. Client (client.py):

   • Spawns the server as a subprocess
   • Establishes stdio-based communication channel
   • Sends JSON-RPC formatted requests
   • Handles responses and displays results to the user

Protocol Flow

Client                          Server
  |                               |
  |--- Initialize Connection ---->|
  |<--- Server Ready -------------|
  |                               |
  |--- List Tools Request ------->|
  |<--- Tools List ---------------|
  |                               |
  |--- Call Tool Request -------->|
  |     (with arguments)          |
  |                               |
  |                          [Execute Tool]
  |                               |
  |<--- Tool Result --------------|
  |                               |

Error Handling

The project includes comprehensive error handling:

• Input Validation: Checks for valid data types and non-empty values
• Network Errors: Gracefully handles API timeouts and connection failures
• Unicode Encoding: Handles special characters in different console environments
• Exception Logging: Server logs all errors for debugging

Limitations

• Weather API requires internet connection
• Weather data depends on wttr.in service availability
• Unicode characters may not display correctly in all terminals

Future Enhancements

• Add more tools (calculator functions, data converters, etc.)
• Implement resource providers for dynamic data
• Add prompt templates for common tasks
• Create a web-based UI
• Add authentication and security features
• Implement caching for API responses
• Add unit tests and integration tests
• Support for multiple weather API providers

Troubleshooting

Issue: "command not found: python"

Solution: Make sure Python is installed and added to your PATH. Try python3 instead of python.

Issue: "ModuleNotFoundError: No module named 'mcp'"

Solution: Install the required package: pip install mcp

Issue: Weather tool returns timeout error

Solution: Check your internet connection and firewall settings. The wttr.in service may also be temporarily unavailable.

Issue: Unicode characters not displaying correctly

Solution: The client automatically falls back to ASCII-only display on Windows. This is expected behavior.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Model Context Protocol - For the MCP specification
• FastMCP - For the MCP server framework
• wttr.in - For the weather API

Author

Hemalathaa Arumugam Elumalai

• GitHub: @hemalathaa90
• LinkedIn: Hemalathaa Arumugam Elumalai

Project Status

🟢 Active Development

---

Built with ❤️ using Python and MCP