I maded this Projects because I wanted to learn more about Model Context Protocols and to learn how to create better README's. I have added simple tools just to have my LLM complete simple task, I plan to add more tool in the future.

Ollama MCP Server

A small Model Context Protocol (MCP) server that gives a local Ollama model a set of safe, sandboxed tools — most importantly the ability to read, write, list, and remove files inside a workspace directory you control.

Everything runs locally. The model, the tools, and your files never leave your machine.

How it works

┌─────────────┐   chat + tool calls   ┌────────────────────┐   MCP (stdio)   ┌──────────────────┐
│   You (CLI) │ ───────────────────▶ │  Ollama client     │ ──────────────▶ │  MCP server      │
│             │ ◀─────────────────── │  (ollama_clients)  │ ◀────────────── │  (server.py)     │
└─────────────┘      responses        └────────────────────┘   tool results   └──────────────────┘
                                              │                                        │
                                              ▼                                        ▼
                                       local Ollama model                     sandboxed workspace
                                       (e.g. qwen2.5:14b)                      (~/Projects/…)

1. You type a message in the client.
2. The client sends it to your local Ollama model along with the list of tools the MCP server exposes.
3. If the model decides to call a tool, the client forwards that call to the MCP server over stdio, gets the result, and feeds it back to the model.
4. The model produces a final answer.

Features

• Sandboxed file tools — the model can only touch files inside the active workspace. Absolute paths, ../ escapes, and protected directories (.git, .venv, .trash, __pycache__) are all rejected.
• Recoverable deletes — remove_project_file and overwrites don't hard-delete. The previous version is moved into <workspace>/.trash/, preserving its layout.
• Atomic writes — files are written to a temp file and os.replace'd into place, so a crash mid-write can't corrupt an existing file.
• Named workspace profiles — switch between project directories via config or an environment variable.
• Size limits — configurable maximum file size for reads and writes.

Available tools

Tool	Description
read_project_file	Read a UTF-8 text file from the workspace.
write_project_file	Create or overwrite a file (overwrite makes a .trash backup).
list_project_items	List files/directories in the workspace (recursive optional).
remove_project_file	Move a file into .trash (recoverable).
ping	Health check — returns pong.
add_numbers	Trivial demo tool that adds two numbers.

Requirements

• Python 3.12+
• Ollama installed and running, with a model pulled (default: qwen2.5:14b).
• Python packages: mcp[cli]==2.0.0, ollama

Installation

# 1. Clone
git clone <your-repo-url> mcp-server
cd mcp-server

# 2. Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install dependencies
pip install "mcp[cli]==2.0.0" ollama

# 4. Pull the model (if you haven't already)
ollama pull qwen2.5:14b

Configuration

All settings live in config.toml:

[ollama]
model = "qwen2.5:14b"     # any model available to your local Ollama
max_tool_rounds = 8       # max tool round-trips per user message

[mcp]
default_workspace = "ollama-workspace" # replace with desired workplace profile
max_list_results = 500
MAX_FILE_SIZE_BYTES = 1000000   # 1 MB read/write cap

[mcp.workspaces]
ollama-workspace = "~/Projects/ollama-workspace" # replace these for your workspace's path
custom-workspace = "~/Projects/Scripts"          # replace these for your workspace's path

Each entry under [mcp.workspaces] is a named profile pointing at a directory the tools are allowed to operate in. The directory is created automatically if it doesn't exist.

Environment variables

Variable	Purpose
OLLAMA_MODEL	Override the model from config.toml.
MCP_WORKSPACE_NAME	Select a named profile from [mcp.workspaces].
MCP_WORKSPACE	Point at a directory directly (bypasses named profiles — handy for testing).
MCP_CONFIG	Use a config file other than ./config.toml.

Getting started

Run the assistant (normal use)

source .venv/bin/activate
python3 clients/ollama_clients.py

You'll see the connected tools and a prompt. Try:

You: create a file called notes.txt that says "hello from ollama"
You: list the files in the workspace
You: read notes.txt

Type exit or quit to stop.

To use a different workspace or model for a session:

MCP_WORKSPACE_NAME="custom-workspace" \
OLLAMA_MODEL="qwen2.5:14b" \
python3 clients/ollama_clients.py

Inspect the server on its own

The MCP CLI inspector lets you call the server's tools directly, without a model:

uv run --with "mcp[cli]==2.0.0" mcp dev ./server/server.py

Maintenance: clearing old trash

Because deletes are recoverable, .trash grows over time. The included script purges trash entries older than a week:

scripts/clean_trash.sh              # clean the configured workspaces
RETENTION_DAYS=14 scripts/clean_trash.sh   # keep two weeks instead

To run it automatically, add a cron entry (daily at 3 AM):

0 3 * * * /path/to/mcp-server/scripts/clean_trash.sh >> $HOME/.mcp-trash-clean.log 2>&1

Project layout

mcp-server/
├── server/
│   └── server.py            # MCP server + tool definitions
├── clients/
│   └── ollama_clients.py    # Ollama <-> MCP bridge (the chat loop)
├── scripts/
│   └── clean_trash.sh       # purges .trash entries older than a week
├── config.toml              # model + workspace configuration
├── tests/                   # (add tests here)
└── README.md