MCPServer (FastMCP) – Ubuntu Setup and GitHub Guide

This repository contains a minimal Model Context Protocol (MCP) server built with FastMCP from the mcp package. It exposes:

• Tools: greet_user(name), add_numbers(a,b), list_files(directory) in server.py
• Example server with resources and prompts in main.py (add, greeting://{name}, and greet_user prompt)

The project is configured with a pyproject.toml that depends on mcp[cli] and includes an optional mcp_settings.json for MCP-aware clients.

Requirements

• Ubuntu (tested on 22.04+)
• Python 3.12+
• Git

Optional:

• uv for faster Python dependency management (you can also use pip)

Quickstart (Ubuntu)

1. Install system prerequisites

sudo apt update
sudo apt install -y python3.12 python3.12-venv git

2. Create and activate a virtual environment

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

3a) Install dependencies with pip

pip install --upgrade pip
pip install "mcp[cli]>=1.25.0"

3b) Or install with uv (optional)

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv
source venv/bin/activate
uv pip install "mcp[cli]>=1.25.0"

Running the server

You have two entry points. Pick the one that matches your use case.

1. Minimal tool server (server.py)

source venv/bin/activate
python server.py

This exposes tools:

• greet_user(name: str) -> str
• add_numbers(a: int, b: int) -> int
• list_files(directory: str = ".") -> str

2. Example server with resources and prompts (main.py)

source venv/bin/activate
python main.py

This exposes:

• Tool: add(a: int, b: int)
• Resource: greeting://{name}
• Prompt: greet_user(name: str, style: str = "friendly")

The example runs with transport="streamable-http" (see main.py).

MCP client settings (optional)

If your MCP client supports a settings file (e.g., Windsurf, IDEs), you can point it to your server via mcp_settings.json:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/absolute/path/to/your/project/venv/bin/python",
      "args": [
        "/absolute/path/to/your/project/server.py"
      ]
    }
  }
}

Note: In this repo, mcp_settings.json is configured with an absolute path under this user's home directory. You should update the paths to match your machine if you use it locally.

Project layout

• server.py – Minimal FastMCP server exposing three tools
• main.py – Demo FastMCP server with a tool, a resource, and a prompt
• pyproject.toml – Project metadata and dependency on mcp[cli]
• mcp_settings.json – Example MCP client configuration (absolute paths; edit for your machine)
• .gitignore – Ignores venv/ and build artifacts

Development tips

• Keep your virtual environment out of Git: .gitignore already excludes .venv and venv/.
• When moving the project to another machine, recreate the venv and install mcp[cli].
• If you want to package this repo later, consider adding a proper module and entry points in pyproject.toml.