> 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 ```mermaid 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 1. **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 2. **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 3. **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 4. **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 5. **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: 1. **Resources**: File-like data that can be read by clients (like API responses or file contents). 2. **Tools**: Functions that can be called by the LLM (with user approval). 3. **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: 1. **Parallel Operations**: Downloads and installs packages in parallel 2. **Efficient Parsing**: Optimized parsing of package metadata 3. **Smart Caching**: Caches wheels and metadata to avoid redundant operations 4. **Native Implementation**: Written in Rust for performance 5. **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: 1. **Simplicity**: Convert Python functions into MCP tools with a single decorator 2. **Type Safety**: Leverages Python type hints for automatic schema generation 3. **Reduced Boilerplate**: Eliminates most of the protocol-level code 4. **Pythonic Design**: Follows Python conventions and best practices 5. **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: 1. **Decorator-based Registration**: Uses decorators to transform regular Python functions into MCP tools and resources 2. **Automatic Type Conversion**: Maps Python types to JSON schema for MCP compliance 3. **Protocol Handling**: Manages all low-level protocol details automatically 4. **Context Management**: Provides an intuitive Context object for accessing MCP capabilities 5. **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.

Why Claude for Desktop and not Claude.ai?

Because servers are locally run, MCP currently only supports desktop hosts.

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.](https://github.com/AjinkyaSambare/mcp-server.git) --- ## 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 ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` #### Windows ```powershell 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 ```bash # 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 ```powershell # 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`: ```python 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`: ```python """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: ```bash 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: 1. **Connect to MCP Servers**: Through various transport methods 2. **Explore Available Capabilities**: View resources, tools, and prompts 3. **Execute Tools**: Test tools with custom inputs 4. **View Resource Content**: Browse and inspect resources 5. **Monitor Messages**: See all protocol messages exchanged 6. **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** 1. Starts your server process using the command you specify 2. Establishes a connection using the specified transport 3. Performs MCP initialization and capability negotiation 4. Discovers available tools, resources, and prompts 5. Renders the appropriate UI elements for each capability 6. Accepts user inputs for testing tools and resources 7. Sends requests to your server based on user actions 8. 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** ```json { "mcpServers": { "calculator": { "command": "uv", "args": [ "--directory", "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\server", "run", "server.py" ] } } } ``` **MacOS/Linux** ```json { "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](https://pypi.org/account/register/) and verify your email on PyPI - Install UV: ```bash curl -Ls https://astral.sh/uv/install.sh | sh ``` Make sure it’s in your PATH: `~/.local/bin/uv` --- ### Build the Package using UV ```bash uv build ``` This creates a `dist/` folder with `.tar.gz` and `.whl` files ### Publish to PyPI using UV ```bash 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: ```bash pip install your-package-name ``` ### Claude Desktop Integration ```bash uv pip install your-package-name ``` #### Manual Configuration (Recommended) ```bash { "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.

UV

UV Documentation MCP Server

File Analysis MCP