MCP Server

A Model Context Protocol (MCP) server implementation that provides various tools for AI agents and LLMs, including search capabilities powered by SearXNG and file system operations.

Features

Web Search: Perform web searches with customizable parameters using SearXNG
File System Operations: Read, write, and manage files with security controls
Extensible Architecture: Add custom tools following the MCP protocol
Docker Support: Easy deployment with Docker and docker-compose
Command-line Interface: Simple management through CLI
Resources and Prompts: Full MCP specification support for resources and prompts

Requirements

Python 3.13 (required)
MCP SDK ≥ 1.6.0
UV package manager for dependency management
Docker (optional, for containerized deployment)

Implementation Approaches

This project demonstrates two approaches to implementing MCP servers:

1. FastMCP Decorator Approach (Recommended)

The simplified approach using FastMCP decorators in mcp_server/server.py:

from mcp.server.fastmcp import FastMCP

# Create server
mcp = FastMCP("MCP Server")

# Add a tool using decorator
@mcp.tool()
def search(query: str, num_results: int = 5) -> dict:
    """Search the web"""
    # Implementation...
    return results

# Add a resource
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a greeting"""
    return f"Hello, {name}!"

# Add a prompt
@mcp.prompt()
def search_prompt(query: str) -> str:
    """Create a search prompt"""
    return f"Please search for: {query}"

2. Original Architecture (Advanced)

The original architecture in mcp_server/core/ provides a more complex implementation with:

ToolRegistry for managing tool registration
MCPTool abstract base class for tool implementation
Singleton MCPServer for server management

This approach offers more flexibility for complex applications but requires more boilerplate code.

Tools

search

Execute web searches through SearXNG with customizable filtering.

Inputs:

query (string): Search terms
num_results (number, optional): Number of results to return (default: 5, max: 20)
language (string, optional): Language code for results (e.g., "en", "fr")
time_range (string, optional): Time range for results (day, week, month, year)
search_category (string, optional): Category to search in (general, images, news, videos)

filesystem

Read, write, and manage files with secure access controls.

Operations:

Read File
- path (string): Path to the file to read
- encoding (string, optional): Encoding to use (default: "utf-8")
- binary (boolean, optional): Whether to read in binary mode (default: false)
Write File
- path (string): Path to write the file
- content (string): Content to write
- encoding (string, optional): Encoding to use (default: "utf-8")
- binary (boolean, optional): Whether to write in binary mode (default: false)
- append (boolean, optional): Whether to append to file (default: false)
List Files
- path (string, optional): Directory to list (default: current directory)
- recursive (boolean, optional): Whether to list recursively (default: false)
- pattern (string, optional): Pattern to match filenames

Configuration

Environment Variables

Configure your MCP server using environment variables:

# Server settings
MCP_SERVER__HOST=0.0.0.0
MCP_SERVER__PORT=8000

# SearXNG settings
MCP_SEARXNG__INSTANCE_URL=http://localhost:8080
MCP_SEARXNG__TIMEOUT=5

# Logging settings
MCP_LOG__LEVEL=INFO

# Data directory
MCP_DATA_DIR=./data

Usage with Claude Desktop

Option 1: Install Simple Example Server

# Install the simple example server directly
mcp install examples/server.py

# Or test with the MCP Inspector
mcp dev examples/server.py

Option 2: Docker Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "8000:8000",
        "-e",
        "MCP_SEARXNG__INSTANCE_URL=http://host.docker.internal:8080",
        "mcp-server"
      ]
    }
  }
}

You'll need to run a SearXNG instance separately:

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "8080:8080",
        "-e", 
        "BASE_URL=http://localhost:8080/",
        "searxng/searxng"
      ]
    }
  }
}

Installation

Docker (Recommended)

# Build the Docker image
docker build -t mcp-server .

# Run the server and SearXNG
docker-compose up

Direct Installation

# Ensure you have Python 3.13 installed
python --version  # Should show Python 3.13.x

# Install uv if you don't have it
pip install uv

# Create a virtual environment and install dependencies
uv venv --python=python3.13
uv install

# Run the server
python -m mcp_server start

Client Examples

See the examples/ directory for client examples:

examples/client.py: Modern client using ClientSession API
examples/simple_client.py: Simple client using direct API calls

Extending with Custom Tools

Using the FastMCP Approach

from mcp_server.server import mcp

@mcp.tool()
def my_custom_tool(param1: str, param2: int = 10) -> dict:
    """My custom tool description"""
    # Implement tool functionality
    return {"result": f"Processed {param1} with {param2}"}

Using the Original Architecture

See the Developer Guide for instructions on adding custom tools with the original architecture.

License

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

Acknowledgements

Model Context Protocol for the protocol specification
SearXNG for the search engine functionality

Command to run the project

python -m mcp_server start --config config.env