Setting Up Custom MCP Servers with Claude Desktop on Debian: A Complete Guide

Background

Since the MCP’s are are the new hot thing, I decided to do my own test.

After installing Claude Desktop on Debian using the community package (since there's no official Linux support yet), I wanted to connect it to my custom weather MCP server built with Python and uv.

My Setup

• OS: Debian 12

• MCP Server: Weather service using Python + uv

• Project code: https://github.com/vbrinza/mcp-weather

Step-by-Step Configuration

1. Create the MCP Server Project

First, I set up my weather MCP server using uv:

uv init weather
cd weather/
source .venv/bin/activate
uv add "mcp[cli]" httpx

This creates the basic project structure and installs the necessary MCP dependencies.

2. There are no Claude Desktop Debian official package yet

However, there are community solutions available:

# Clone the community repository
git clone https://github.com/aaddrick/claude-desktop-debian.git
cd claude-desktop-debian

# Run the build script to create and install the package
./build.sh

# Install the binary
sudo apt install ./claude-desktop_0.12.129_amd64.deb

3. Find the Config File

The Claude Desktop's configuration file location on Debian is":

~/.config/Claude/claude_desktop_config.json

If it doesn't exist yet, create the directory and file:

mkdir -p ~/.config/Claude
touch ~/.config/Claude/claude_desktop_config.json

4. Configure the MCP Server

Here's the working configuration I ended up with:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["--directory", "~/home/vbrinza/work/weather", "run", "weather.py"],
      "env": {
        "PYTHONPATH": "~/work/weather"
      }
    }
  }
}

Key Points:

• The server name ("weather") can be anything you want

• command is the executable (uv in my case)

• args array contains all the command-line arguments

• env object lets you set environment variables if needed

5. Restart Claude Desktop

After saving the config:

# Kill existing processes
pkill -f claude-desktop

# Restart
claude-desktop

6. My project structure

For reference, here's how my weather directory is organized:

~/work/weather/
├── main.py
├── pyproject.toml
├── README.md
├── uv.lock
└── weather.py

The project was initialized with uv init weather and the MCP dependencies were added with uv add "mcp[cli]" httpx. The weather.py script implements the MCP protocol and exposes weather-related functions that Claude can call.

Verifying It Works

Once configured correctly:

1. Open Claude Desktop

Check the weather MCP is active

2. Start a new conversation

3. Ask something that would trigger your MCP server (e.g., "Whats the weather in New York?")

4. You should see Claude using your custom server's functions

What’s happening under the hood

When you ask a question:

1. The client sends your question to Claude

2. Claude analyzes the available tools and decides which one(s) to use

3. The client executes the chosen tool(s) through the MCP server

4. The results are sent back to Claude

5. Claude formulates a natural language response

6. The response is displayed to you!