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
• Configuration
• Run server in STDIO mode
• Run server in SSE mode
• Configure Claude Desktop
• Available tools
• Create new tool
• Debug in VSCode

---

Prerequisites

• Python >= 3.11
• uv and pip installed

↑ index

---

Configuration

Init virtualenv and install dependencies with:

uv venv
source .venv/bin/activate
uv sync

Create your .env file by copying:

cp env.dist .env

Then, customize it if needed.

↑ index

---

Run server in STDIO mode

First of all, to test the server, install and run a MCP Inspector with:

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:

uv run python -m app.main

↑ index

---

Run server in SSE mode

If you want to use the server through SSE from remote agents, launch it with:

uv run python -m app.main --sse --port 8000

As the STDIO mode, you can test it with MCP Inspector (remote) with:

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:

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:

python3 stdio_test.py

You will see a the available tools list and the result of calculate.

↑ index

---

Configure Claude Desktop

If you want to use tools on Claude Desktop, create the file claude_desktop_config.json with this content:

{
  "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

---

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

---

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:

  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:

  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

---

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):

{
  "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

---

Made with ♥️ by Alessandro Orrù