📌Overview

Purpose: EasyMCP is designed to facilitate the connection to various Model Context Protocol (MCP) servers, enhancing interaction with tools and the OpenAI API for an improved user experience.

Overview: EasyMCP is a versatile client that allows users, especially beginners, to connect to multiple types of MCP servers (SSE, NPX, UV). It streamlines communication with these servers for tasks like file operations and provides an interactive chat experience using OpenAI’s capabilities.

Key Features:

• Multiple Server Support:
  Connect to SSE, NPX, and UV servers, enabling a broad range of functionalities tailored for different environments.

• Dynamic Tool Integration:
  Automatically fetch and utilize available tools from connected servers to efficiently handle user queries.

• Interactive Chat Loop:
  Engage in a seamless query-response interaction with the client, leveraging OpenAI and MCP tools for enriched communication.

• Configuration Management:
  Simplify server configuration additions with an easy-to-use script, allowing smooth updates to server JSON files.

---

EasyMCP

EasyMCP is a flexible and beginner-friendly client for the Model Context Protocol (MCP). It allows you to connect to different types of MCP servers—SSE, NPX, and UV—enabling interaction with various tools (e.g., file operations) and integration with the OpenAI API for an enhanced chat experience.

Features

• Multiple Server Support
  • SSE Servers: Connect via Server-Sent Events using a server URL.
  • NPX Servers: Launch servers using NPX commands (compatible with Windows and non-Windows systems).
  • UV Servers: Run servers configured with UV commands.
• Dynamic Tool Integration:
  The client automatically retrieves available tools from the connected server and uses them to process user queries.
• Interactive Chat Loop:
  Type queries and let the client process responses using OpenAI and the available MCP tools.
• Configuration Management:
  Easily add new server configurations with add_server.py, which updates the appropriate configuration file (sse_servers.json, npx_servers.json, or uv_servers.json).

Prerequisites

• Python 3.10+ (for compatibility with asyncio and modern async features)
• A valid OpenAI API key (set in your .env file)
• Other API keys as needed for additional integrations

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/EasyMCP.git
   cd EasyMCP
   

2. Create a virtual environment and activate it:

   On Windows:

   python -m venv .venv
   .venv\Scripts\activate
   

   On macOS/Linux:

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install the required packages:

   pip install -r requirements.txt
   

4. Set up your environment variables:
   Rename .env.sample to .env (or create your own .env) and fill in the necessary API keys and configurations.

Server Configuration Files

EasyMCP uses JSON configuration files to manage servers:

• sse_servers.json: Configurations for SSE-based servers.
  Example:

  {
    "mcpServers": {
      "@modelcontextprotocol/time": {
        "url": "https://router.mcp.so/sse/pnabizm8lkazpr"
      }
    }
  }
  

• npx_servers.json: Configurations for NPX servers.
  Example:

  {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "C:\\Users\\lotus\\Documents\\llm_books_papers",
          "C:\\Users\\lotus\\Documents\\llm_books_papers"
        ]
      }
    }
  }
  

• uv_servers.json: Configurations for UV servers.
  Example:

  {
    "mcpServers": {
      "sqlite": {
        "command": "uv",
        "args": [
          "--directory",
          "parent_of_servers_repo/servers/src/sqlite",
          "run",
          "mcp-server-sqlite",
          "--db-path",
          "~/test.db"
        ]
      }
    }
  }
  

Usage

1. Run the MCP Client:

   python main.py
   

2. Select a Server:
   The client loads available servers from sse_servers.json, npx_servers.json, and uv_servers.json. Enter the corresponding number to select a server.

3. Interact With the Client:
   Once connected, type your queries, for example:

   • To read a PDF file: read Build a Large Language Model.pdf
   • To use a file tool: use read_file tool and read 2308.11432v5.pdf

   The client will help construct proper file paths based on allowed directories provided by the MCP server.

Adding a New Server

To add a new MCP server configuration:

1. Prepare your JSON configuration for the new server.

2. Run add_server.py:

   python add_server.py
   

   This script detects the server type (NPX, UV, or SSE) and appends the new configuration to the appropriate file (npx_servers.json, uv_servers.json, or sse_servers.json).

Example Files

• main.py: The main client entry point, handling server connections, the chat loop, and query processing with OpenAI integration.
• add_server.py: Script to add new MCP server configurations.
• .env: Environment variables including API keys and model settings.
• requirements.txt: Project dependencies.

Contributing

Contributions are welcome! Please fork the repository and submit pull requests with descriptions of your changes.

License

This project is open source under the MIT License.

Contact

For questions or feature requests, feel free to open an issue in the GitHub repository.

Happy coding!