# Fifth Elephant MCP Server: A DIY Guide

This guide provides a complete walkthrough to create and run a simple Model Context Protocol (MCP) server from scratch.

## Table of Contents

1. [Prerequisites](#prerequisites)
   - [Install pyenv](#1-install-pyenv-if-not-already-installed)
   - [Install Python 3.11](#2-install-python-311)
   - [Install uv](#3-install-uv)
2. [Step 1: Project Setup](#step-1-project-setup)
3. [Step 2: Initialize a Python Project with uv](#step-2-initialize-a-python-project-with-uv)
4. [Step 3: Create and Activate Virtual Environment](#step-3-create-and-activate-virtual-environment)
5. [Step 4: Sync Dependencies (Not Required)](#step-4-sync-dependencies)
6. [Step 5: Add MCP Dependency](#step-5-add-mcp-dependency)
7. [Step 6: Verify Installation](#step-6-verify-installation)
8. [Step 7: Edit the Server Code](#step-7-edit-the-server-code)
9. [Step 8: Debug Locally with MCP Inspector](#step-8-debug-locally-with-mcp-inspector)
10. [Step 9: Configure Claude Desktop](#step-9-configure-claude-desktop)
11. [Troubleshooting](#troubleshooting)

## Prerequisites

Before we begin, ensure you have the following installed:

### 1. Install pyenv (if not already installed)

pyenv allows you to manage multiple Python versions easily.

**macOS:**
```sh
brew install pyenv
```

**Linux:**
```sh
curl https://pyenv.run | bash
```

**Windows:**
```powershell
# Install pyenv-win using PowerShell
Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"
```

Add pyenv to your shell profile:

**macOS/Linux (zsh):**
```sh
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc
```

**Windows:**
```powershell
# Restart your PowerShell or Command Prompt after installation
# pyenv-win will be automatically added to your PATH
```

### 2. Install Python 3.11

Install and set Python 3.11 as your local version:

```sh
pyenv install 3.11.9
pyenv local 3.11.9
```

Verify the Python version:
```sh
python --version
# Should output: Python 3.11.9
```

### 3. Install uv

Install [uv](https://github.com/astral-sh/uv) for fast Python package management:

**macOS/Linux:**
```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows:**
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Verify uv installation:
```sh
uv --version
```

## Step 1: Project Setup

First, create a directory for your project and navigate into it.

```sh
mkdir fifth-elephant-mcp
cd fifth-elephant-mcp
```

## Step 2: Initialize a Python Project with `uv`

Initialize a new Python project using `uv`. This will create a virtual environment and a `pyproject.toml` file.

```sh
uv init --quiet
```

## Step 3: Create and Activate Virtual Environment

Create a virtual environment using Python 3.11:

```sh
uv venv --python 3.11.9
```

Activate the virtual environment:

**macOS/Linux:**
```sh
source .venv/bin/activate
```


**Windows (Command Prompt):**
```cmd
.venv\Scripts\activate.bat
```

Verify you're in the virtual environment (you should see `(.venv)` in your terminal prompt).

## Step 4: Sync Dependencies (not required)

Sync the project dependencies to ensure everything is up to date:

```sh
uv sync
```

## Step 5: Add MCP Dependency

Add the `mcp` library with CLI extras to your project's dependencies.

```sh
uv add "mcp[cli]"
```

**Note:** When installing MCP CLI, it may ask you to install additional dependencies. Press `y` to confirm.

## Step 6: Verify Installation

Verify that all components are properly installed:

```sh
# Verify Python version
python --version
# Should output: Python 3.11.9

# Verify uv version
uv --version

# Verify MCP library is installed (should be version 1.11 or later)
python -c "from mcp.server.fastmcp import __version__; print(__version__)"    
```

## Step 7: Edit the Server Code

When you ran `uv init`, a `main.py` file was already created. Edit this file and replace its contents with the following code. This code sets up a `FastMCP` server with two tools: `hello_world` and `add`.

```python
from mcp.server.fastmcp import FastMCP

# Create an MCP server
mcp = FastMCP("Fifth Elephant")


# Add a hello world tool
@mcp.tool()
def hello_world() -> str:
    """Returns a friendly greeting."""
    return "hello world"


# Add an addition tool
@mcp.tool()
def add(a: int, b: int) -> int:
    """Adds two numbers together."""
    return a + b


if __name__ == "__main__":
    mcp.run()
```

## Step 8: Debug Locally with MCP Inspector

For development and testing, you can use the MCP inspector.

Run the following command - 
```
uv run mcp dev main.py
```

This will spin up the inspector. It will open in your browser. Press connect on the left sidebar.

## Step 9: Configure Claude Desktop

If you haven't already, install Claude Desktop to use your MCP server:

1. Download Claude Desktop from [claude.ai](https://claude.ai/download)
2. Install and set up Claude Desktop

To use your MCP server with Claude Desktop, you need to configure it using absolute paths.

### Get Absolute Paths

First, get the absolute paths for your virtual environment's Python and your main.py file:

```sh
# Get the absolute path to your virtual environment's Python
which python

# Get the absolute path to your main.py file
pwd
```

**Windows (Command Prompt):**
```cmd
# Get the absolute path to your virtual environment's Python
where python

# Get the absolute path to your main.py file
cd
```

### Configure Claude Desktop

1. Open Claude Desktop
2. Go to Settings → Developer → Edit Config
3. Add your MCP server configuration to the `config.json` file:

**macOS/Linux:**
```json
{
  "mcpServers": {
    "fifth-elephant": {
      "command": "/absolute/path/to/your/.venv/bin/python",
      "args": ["/absolute/path/to/your/main.py"]
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "fifth-elephant": {
      "command": "C:\\absolute\\path\\to\\your\\.venv\\Scripts\\python.exe",
      "args": ["C:\\absolute\\path\\to\\your\\main.py"]
    }
  }
}
```

**Important:** 
- **macOS/Linux:** Replace `/absolute/path/to/your/.venv/bin/python` and `/absolute/path/to/your/main.py` with the actual absolute paths you obtained from the `which python` and `pwd` commands.
- **Windows:** Replace `C:\\absolute\\path\\to\\your\\.venv\\Scripts\\python.exe` and `C:\\absolute\\path\\to\\your\\main.py` with the actual absolute paths you obtained from the `where python` and `cd`/`Get-Location` commands. Note the double backslashes (`\\`) in Windows paths.

**Config file locations:**
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/claude/claude_desktop_config.json`

## Troubleshooting

If you encounter issues, try these common solutions:

### 1. Virtual Environment Issues

Make sure your virtual environment is activated:

**macOS/Linux:**
```sh
# Activate the virtual environment
source .venv/bin/activate

# Verify you're in the virtual environment
which python
# Should show: /path/to/your/project/.venv/bin/python
```


**Windows (Command Prompt):**
```cmd
# Activate the virtual environment
.venv\Scripts\activate.bat

# Verify you're in the virtual environment
where python
# Should show: C:\path\to\your\project\.venv\Scripts\python.exe
```

### 2. Dependency Issues

Sync your dependencies:
```sh
uv sync
```

### 3. MCP Inspector Configuration

If you're using the MCP inspector and having issues, use these settings:

- **Command:** `uv`
- **Args:** `run --with mcp mcp run main.py`

**Note:** The command should be `uv`, not `mcp-server-everything` or similar variants.

### 4. Path Issues

Ensure you're using absolute paths in your Claude Desktop configuration. Use:

**macOS/Linux:**
```sh
# Get absolute path to Python in your virtual environment
which python

# Get absolute path to your project directory
pwd
```


**Windows (Command Prompt):**
```cmd
# Get absolute path to Python in your virtual environment
where python

# Get absolute path to your project directory
cd
```

Then update your `config.json` with the complete absolute paths. Remember to use double backslashes (`\\`) for Windows paths in JSON.