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ù