File Analysis MCP - MCP Server

Get started building your own server to use in Claude for Desktop and other clients.

This README file provides a comprehensive guide on creating a custom MCP server and publishing it as a package to PyPI. Follow the steps outlined to build, configure, and deploy your server effectively.

What is Model Context Protocol (MCP)?

MCP stands for Model Context Protocol — it's a protocol that allows developers to extend AI assistants (like Claude) with custom tools and servers.

Example: You can build weather servers, calculators, finance assistants, or anything you imagine.

MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.

General Architecture

flowchart LR
    subgraph "Your Computer"
        Host["Host with MCP Client\n(Claude, IDEs, Tools)"]
        S1["MCP Server A"]
        S2["MCP Server B"]
        S3["MCP Server C"]
        Host <-->|"MCP Protocol"| S1
        Host <-->|"MCP Protocol"| S2
        Host <-->|"MCP Protocol"| S3
        S1 <--> D1[("Local\nData Source A")]
        S2 <--> D2[("Local\nData Source B")]
    end
    subgraph "Internet"
        S3 <-->|"Web APIs"| D3[("Remote\nService C")]
    end

Detailed Architecture Explanation

Host with MCP Client (e.g., Claude Desktop):
- This is the application where the LLM (like Claude) runs
- Contains MCP client implementations that communicate with servers
- Manages user interactions and presents results
- Responsible for routing requests between the user, LLM, and appropriate servers
MCP Server A, B, C:
- Independent processes running on your local machine
- Each server provides specific functionality (e.g., file analysis, database access, weather data)
- Servers run in isolated environments with their own dependencies
- Can be written in different languages (Python, TypeScript, Java, etc.)
- Communicate with the host using the standardized MCP protocol
Local Data Sources:
- Files, databases, or other resources on your local machine
- Accessed securely by the MCP servers
- Data never leaves your machine unless explicitly designed to do so
- Examples: Your documents, local SQLite databases, configuration files
Remote Services:
- External APIs and web services on the internet
- MCP servers can act as secure bridges to these services
- Examples: Weather APIs, stock data, news services
MCP Protocol:
- Standardized communication format between clients and servers
- Uses JSON-RPC 2.0 over various transport layers
- Structured message types for requests, responses, and notifications
- Capability negotiation to enable feature discovery

Key Components

MCP Hosts: Programs like Claude Desktop, IDEs, or AI tools that want to access data through MCP.
MCP Clients: Protocol clients that maintain 1:1 connections with servers.
MCP Servers: Lightweight programs that each expose specific capabilities through the standardized Model Context Protocol.
Local Data Sources: Your computer's files, databases, and services that MCP servers can securely access.
Remote Services: External systems available over the internet (e.g., through APIs) that MCP servers can connect to.

Why MCP?

MCP helps you build agents and complex workflows on top of LLMs. LLMs frequently need to integrate with data and tools, and MCP provides:

A growing list of pre-built integrations that your LLM can directly plug into.
The flexibility to switch between LLM providers and vendors.
Best practices for securing your data within your infrastructure.

What is an MCP Server?

A Model Context Protocol (MCP) server is a service that connects AI models to external data sources and tools.

Core MCP Concepts

MCP servers can provide three main types of capabilities:

Resources: File-like data that can be read by clients (like API responses or file contents).
Tools: Functions that can be called by the LLM (with user approval).
Prompts: Pre-written templates that help users accomplish specific tasks.

What is UV?

UV is a modern, fast Python package installer and resolver built in Rust. It's designed as a replacement for tools like pip, pipx, and poetry, offering significant performance improvements while maintaining compatibility.

Key UV Features

Speed: Often 10-100x faster than pip due to Rust implementation
Compatibility: Maintains compatibility with pip, requirements.txt, and pyproject.toml
Isolation: Creates clean, reproducible environments
Caching: Intelligent caching system to avoid redundant downloads
Modern Resolver: Efficient dependency resolution algorithm

How UV Works

UV accelerates Python package management through:

Parallel Operations: Downloads and installs packages in parallel
Efficient Parsing: Optimized parsing of package metadata
Smart Caching: Caches wheels and metadata to avoid redundant operations
Native Implementation: Written in Rust for performance
Wheel Prioritization: Prioritizes wheels over source distributions

UV vs Other Package Managers

| Feature | UV | pip | pipx | Poetry | |---------|----|----|------|--------| | Speed | Extremely Fast | Slower | Moderate | Moderate | | Native Language | Rust | Python | Python | Python | | Environment Management | Yes | Limited | Yes | Yes | | Lock Files | Yes | No | No | Yes | | Dependency Resolution | Advanced | Basic | Basic | Advanced | | Project Creation | Yes | No | No | Yes | | MCP Integration | Native Support | Requires extra setup | Limited | Limited |

UV is particularly well-suited for MCP server development because:

Claude Desktop uses UV to manage server environments
It creates isolated environments that prevent dependency conflicts
Faster installation means quicker development cycles
The uv init command sets up project structures efficiently

What is FastMCP?

FastMCP is a high-level, Pythonic framework for building MCP servers. It significantly simplifies the process of creating MCP-compatible tools, resources, and prompts by providing intuitive decorators and abstractions over the lower-level MCP protocol.

Why FastMCP?

While there are several ways to build MCP servers, FastMCP stands out for several reasons:

Simplicity: Convert Python functions into MCP tools with a single decorator
Type Safety: Leverages Python type hints for automatic schema generation
Reduced Boilerplate: Eliminates most of the protocol-level code
Pythonic Design: Follows Python conventions and best practices
Fast Development: Significantly reduces development time

FastMCP vs Alternatives

| Feature | FastMCP | Raw MCP SDK | Custom Implementation | |---------|---------|------------|----------------------| | Ease of Use | ★★★★★ | ★★★☆☆ | ★☆☆☆☆ | | Flexibility | ★★★★☆ | ★★★★★ | ★★★★★ | | Development Speed | ★★★★★ | ★★★☆☆ | ★★☆☆☆ | | Maintainability | ★★★★★ | ★★★☆☆ | ★★☆☆☆ | | Protocol Compliance | ★★★★★ | ★★★★★ | Varies |

How FastMCP Works

FastMCP operates through these key mechanisms:

Decorator-based Registration: Uses decorators to transform regular Python functions into MCP tools and resources
Automatic Type Conversion: Maps Python types to JSON schema for MCP compliance
Protocol Handling: Manages all low-level protocol details automatically
Context Management: Provides an intuitive Context object for accessing MCP capabilities
Transport Abstraction: Handles different transport mechanisms without developer involvement

What We'll Be Building

Basic Math Calculator MCP

A Model Context Protocol (MCP) server providing tools for basic mathematical operations.

Features

Basic math operations (addition, subtraction, multiplication, division)
Error handling for edge cases (like division by zero)
Basic help information via MCP resources

Note: We've chosen Claude Desktop here for demonstration purposes.

<details> <summary>Why Claude for Desktop and not Claude.ai?</summary> Because servers are locally run, MCP currently only supports desktop hosts. </details>

This tutorial will primarily focus on tools.

Let's get started with building our basic math calculator server!
You can find the complete code for what we'll be building here.

Prerequisite Knowledge

This quickstart assumes you have familiarity with:

Python
LLMs like Claude

System Requirements

Python 3.10 or higher installed.
You must use the Python MCP SDK 1.2.0 or higher.

Set Up Your Environment

First, let's install uv and set up our Python project and environment:

UV: A fast Python package and project manager, written in Rust.

MacOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Note: Restart your terminal afterwards to ensure that the uv command gets picked up.

Create and Set Up Your Project

MacOS/Linux

# Create a new directory for our project
uv init basic_math_calculator_mcp
cd basic_math_calculator_mcp

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]"

# Create our server directory and files
mkdir -p src/basic_math_calculator_mcp
touch src/basic_math_calculator_mcp/server.py
touch src/basic_math_calculator_mcp/__init__.py

Here's an explanation of each command :

uv init basic_math_calculator_mcp - Creates a new project directory named "basic_math_calculator_mcp" using the UV package manager.

cd basic_math_calculator_mcp - Changes your current directory to the newly created project folder.

uv venv - Creates a Python virtual environment to isolate project dependencies.

source .venv/bin/activate - Activates the virtual environment so installed packages go into this environment.

uv add "mcp[cli]" - Installs the Model Context Protocol SDK with its command-line interface tools.

mkdir -p src/basic_math_calculator_mcp - Creates a source directory structure following Python package standards.

touch src/basic_math_calculator_mcp/server.py - Creates an empty server.py file where you'll write the MCP server code

touch src/basic_math_calculator_mcp/__init__.py - Creates an empty init.py file that marks the directory as a Python package.

Windows

# Create a new directory for our project
uv init basic_math_calculator_mcp
cd basic_math_calculator_mcp

# Create virtual environment and activate it
uv venv
.venv\Scripts\activate

# Install dependencies
uv add "mcp[cli]"

# Create our server directory and files
mkdir -p src\basic_math_calculator_mcp
new-item src\basic_math_calculator_mcp\server.py
new-item src\basic_math_calculator_mcp\__init__.py

Building Your Server

Importing Packages and Setting Up the Instance

Let's implement our server in src/basic_math_calculator_mcp/server.py:

from mcp.server.fastmcp import FastMCP, Context

# Create an MCP server specifically for basic math operations
mcp = FastMCP(
    "Basic Math Calculator",
    dependencies=[]  # No external dependencies needed for basic math
)

# Basic mathematical operations
@mcp.tool()
def add(a: float, b: float) -> float:
    """
    Add two numbers together.
    
    Args:
        a: First number
        b: Second number
        
    Returns:
        The sum of a and b
    """
    return a + b

@mcp.tool()
def subtract(a: float, b: float) -> float:
    """
    Subtract the second number from the first.
    
    Args:
        a: Number to subtract from
        b: Number to subtract
        
    Returns:
        The result of a - b
    """
    return a - b

@mcp.tool()
def multiply(a: float, b: float) -> float:
    """
    Multiply two numbers together.
    
    Args:
        a: First number
        b: Second number
        
    Returns:
        The product of a and b
    """
    return a * b

@mcp.tool()
def divide(a: float, b: float) -> str:
    """
    Divide the first number by the second.
    
    Args:
        a: Numerator
        b: Denominator
        
    Returns:
        The result of a / b
    """
    if b == 0:
        return "Error: Division by zero is not allowed"
    return str(a / b)

# A resource with basic calculator instructions
@mcp.resource("calculator://help")
def calculator_help() -> str:
    """Basic calculator help information."""
    return """
    # Basic Math Calculator
    
    This calculator provides the following operations:
    
    - Addition: Use the `add` tool with two numbers
    - Subtraction: Use the `subtract` tool with two numbers
    - Multiplication: Use the `multiply` tool with two numbers
    - Division: Use the `divide` tool with two numbers
    
    Example:
    - To add 5 and 3, use: `add(5, 3)`
    """

def run():
    """Run the MCP server"""
    mcp.run()

if __name__ == "__main__":
    run()

Code explanation:

from mcp.server.fastmcp import FastMCP, Context - Imports the FastMCP framework and Context for creating MCP servers
mcp = FastMCP("Basic Math Calculator", dependencies=[]) - Creates the server with a name and no dependencies
@mcp.tool() - Decorator to register a function as an MCP tool
add(a: float, b: float) -> float - Addition function taking two arguments and returning their sum
subtract(a: float, b: float) -> float - Subtraction function
multiply(a: float, b: float) -> float - Multiplication function
divide(a: float, b: float) -> str - Division function with zero division handling
@mcp.resource("calculator://help") - Registers a resource at the given URI
calculator_help() -> str - Function that returns help information
run() - Function to start the server
if __name__ == "__main__": run() - Runs the server when the file is executed directly

Create the Package Initialization

In src/basic_math_calculator_mcp/__init__.py:

"""Basic Math Calculator MCP Server - Tools for performing basic math operations"""

from .server import mcp, run

__version__ = "0.1.0"

Your server is complete! Run uv run server.py to confirm that everything's working.

Testing and Debugging

Running with the MCP Inspector:

uv run mcp dev path/to/your/server/file

The MCP Inspector is an interactive developer tool for testing and debugging MCP servers.

What is the MCP Inspector?

The MCP Inspector is a browser-based interactive development environment for testing and debugging MCP servers. It provides a visual interface that allows you to:

Connect to MCP Servers: Through various transport methods
Explore Available Capabilities: View resources, tools, and prompts
Execute Tools: Test tools with custom inputs
View Resource Content: Browse and inspect resources
Monitor Messages: See all protocol messages exchanged
Debug Issues: Identify and fix problems in your server

How the MCP Inspector Works

The MCP Inspector operates through these key components:

Server Launcher , Transport Bridge , Web Interface , Testing Facilities , Debugging Tools

Starts your server process using the command you specify
Establishes a connection using the specified transport
Performs MCP initialization and capability negotiation
Discovers available tools, resources, and prompts
Renders the appropriate UI elements for each capability
Accepts user inputs for testing tools and resources
Sends requests to your server based on user actions
Displays results and any errors that occur

Testing Your Server with Claude for Desktop

Note: Claude for Desktop is not yet available on Linux.

Configure Claude for Desktop

Open your Claude for Desktop App configuration file at:

MacOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: $env:AppData\Claude\claude_desktop_config.json

If the file doesn't exist, create it.

Example Configuration

Windows

{
    "mcpServers": {
        "calculator": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\server",
                "run",
                "server.py"
            ]
        }
    }
}

MacOS/Linux

{
    "mcpServers": {
        "calculator": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/server",
                "run",
                "server.py"
            ]
        }
    }
}

Warning: You may need to provide the full path to the uv executable in the command field. Use which uv (MacOS/Linux) or where uv (Windows) to find it.

Save the file and restart Claude for Desktop.

Deploying and Publishing Your MCP Server on PyPI

What is PyPI?

PyPI (Python Package Index) is the official repository of Python packages. It acts as a central hub where Python developers can upload, share, and distribute their code so others can easily install it via pip.

Why PyPI?

Centralized Distribution: Easily reach a wide Python audience.
Easy Installation: Just pip install package-name.
Version Control: Maintain and distribute multiple versions.
Integration: Works seamlessly with tools like pip, build, twine, and uv.

Alternatives to PyPI

| Alternative | Description | Comparison with PyPI | |---------------------|-------------|------------------------| | TestPyPI | A staging version of PyPI | Used for testing before production release | | GitHub Releases | Distribute wheels or source code via GitHub | Manual installation; lacks automation and discoverability | | Private Indexes | Self-hosted (e.g., Nexus, Artifactory) | Good for internal/org use; not public | | Conda | For data science and scientific computing environments | Better for binary packages but separate ecosystem |

Bottom Line: PyPI remains the most popular and widely adopted platform for Python package distribution.

Publishing Your MCP Server to PyPI

We'll use UV – a fast, modern Python packaging tool – instead of traditional tools like build and twine.

Prerequisites

Python project with pyproject.toml and optional README.md, LICENSE, and __init__.py
Register and verify your email on PyPI
Install UV:

curl -Ls https://astral.sh/uv/install.sh | sh

Make sure it’s in your PATH: ~/.local/bin/uv

Build the Package using UV

uv build

This creates a dist/ folder with .tar.gz and .whl files

Publish to PyPI using UV

uv publish

You’ll be prompted to enter your PyPI username/password or API token (recommended).

If successful, you’ll see:

Uploading your-package-nam-veriosn-py3-none-any.whl to PyPI
View at: https://pypi.org/project/your-package-name

Why UV Instead of Twine/Build?

| Tool | Role | Pros | Cons | |----------|------------------|-------------------------------|-------------------------------| | UV | Build + Publish | Fast, modern, single command | Still new, evolving | | Twine | Only uploads | Well-established | Requires separate build step | | Build | Only builds | Simple and reliable | Requires pairing with Twine |

Sharing the Package with Other Users

Standard Sharing

Share the PyPI link: https://pypi.org/project/your-package-name
Others can install via:

pip install your-package-name

Claude Desktop Integration

uv pip install your-package-name

Manual Configuration (Recommended)

{
  "mcpServers": {
    "mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "mcp-server"
      ]
    }
  }
}

Summary

PyPI is the go-to platform for public Python packages.
UV simplifies the process of building and publishing.
Use TestPyPI to verify before full release.
Your MCP server can be installed and run via CLI or code.
Share with users through PyPI link and Claude Desktop integration.

You are now ready to build, publish, and distribute your MCP server with confidence.