mcp-server

# Simple MCP server with tools for AI agents A fast and lightweight **MCP server** with different tools for AI agents. It supports STDIO (Claude Desktop) and SSE (remote agents). ## Index - [Prerequisites](#prerequisites) - [Configuration](#configuration) - [Run server in STDIO mode](#run-server-in-stdio-mode) - [Run server in SSE mode](#run-server-in-sse-mode) - [Configure Claude Desktop](#configure-claude-desktop) - [Available tools](#available-tools) - [Create new tool](#create-new-tool) - [Debug in VSCode](#debug-in-vscode) --- ## Prerequisites - Python >= 3.11 - uv and pip installed [↑ index](#index) --- ## Configuration Init **virtualenv** and install dependencies with: ```bash uv venv source .venv/bin/activate uv sync ``` Create your ```.env``` file by copying: ```bash cp env.dist .env ``` Then, customize it if needed. [↑ index](#index) --- ## Run server in STDIO mode First of all, to test the server, install and run a MCP Inspector with: ```bash npx @modelcontextprotocol/inspector uv run python -m app.main ``` At the end, a UI will open in your browser. Connect to the server by clicking **Connect** on the left menu. Then, from the top bar, click on **Tools** and **List tools**. At this point you can choose you preferred tools and play with it. If you want to test it without the inspector, simply launch with: ```bash uv run python -m app.main ``` [↑ index](#index) --- ## Run server in SSE mode If you want to use the server through **SSE** from remote agents, launch it with: ```bash uv run python -m app.main --sse --port 8000 ``` As the STDIO mode, you can test it with MCP Inspector (remote) with: ```bash npx @modelcontextprotocol/inspector ``` If you want to simulate a tool call from a remote agent, create a simple **STDIO client** in python (e.g. `stdio_test.py`) with this code: ```python import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def test(): server_params = StdioServerParameters(command="uv", args=["run", "python", "server.py"], cwd="./") async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() # Tools list tools = await session.list_tools() print("Tools:", [t.name for t in tools.tools]) # Call calculate result = await session.call_tool("calculate", { "operation": "multiply", "a": 6, "b": 7 }) print("Result:", result.content) asyncio.run(test()) ``` Then run with: ```bash python3 stdio_test.py ``` You will see a the **available tools list** and the result of `calculate`. [↑ index](#index) --- ## Configure Claude Desktop If you want to use tools on **Claude Desktop**, create the file `claude_desktop_config.json` with this content: ```json { "mcpServers": { "mcp-server-tools": { "command": "uv", "args": ["run", "--directory", "/path/to/mcp-server", "python", "-m", "app.main"] } } } ``` Move this file in: - macOS: `~/Library/Application Support/Claude` - Windows: `%APPDATA%\Claude` [↑ index](#index) --- ## Available tools | Tool | Descrizione | | :--- | :--- | | `calculate` | Math operations (add, subtract, multiply, divide, power) | | `get_datetime` | Date/hour with timezone and configurable format | | `process_text` | Text handler (word count, extract email/URL, stats) | | `fetch_url` | HTTP GET/HEAD requests | | `convert_data` | JSON, Base64, Hex conversions | [↑ index](#index) --- ### Create new tool To create new tool you need to: - Create a new file (e.g. `app/tools/my_new_tool.py`) - Write your logic keeping this structure: ```python from app.mcp import mcp @mcp.tool() def my_new_tool(your_param: str) -> dict[str, Any]: """ Clear and exaustive tool description. Args: your_param: clear and exaustive param description Returns: Clear and exaustive result description """ # YOUR LOGIC HERE if some_error: return {"success": False, "error": "Clear error description"} return { "success": True, "your_resp": "...", "other_resp": "...", } ``` - Edit `app/tools/__init__.py` file and add your tool: ```python from app.tools import my_new_tool __all__ = [ "my_new_tool", ] ``` - Restart your server In the same way, if you want to **delete** an existing tool, simply delete it from `__init__.py` and delete the related `.py` file. [↑ index](#index) --- ### Debug in VSCode To debug your Python microservice you need to: - Install **VSCode** - Ensure you have **Python extension** installed - Ensure you have selected the **right interpreter with virtualenv** on VSCode - Click on **Run and Debug** menu and **create a launch.json file** - From dropdown, select **Python debugger** and **FastAPI** - Change the ```.vscode/launch.json``` created in the project root with this (customizing host and port if changed): ```json { "version": "0.2.0", "configurations": [ { "name": "MCP Server (SSE)", "type": "debugpy", "request": "launch", "module": "app.main", "args": [ "--sse", "--port", "8000", "--reload" ], "envFile": "${workspaceFolder}/.env", "console": "integratedTerminal", "cwd": "${workspaceFolder}", "justMyCode": true }, { "name": "MCP Server (STDIO)", "type": "debugpy", "request": "launch", "module": "app.main", "args": [ "--reload" ], "envFile": "${workspaceFolder}/.env", "console": "integratedTerminal", "cwd": "${workspaceFolder}", "justMyCode": true } ] } ``` - Put some breakpoint in the code, then press the **green play button** - Call the API to debug [↑ index](#index) --- Made with ♥️ by Alessandro Orrù