LottaLai/nibble-pixie-mcp-server

Nibble Pixie MCP Server

A fastmcp-based Model Context Protocol (MCP) server implementation.

Overview

This project provides a MCP server built with the fastmcp framework. It exposes tools, resources, and prompts that can be used by MCP clients like Claude Desktop.

Features

• Tools: Execute functions like add and multiply
• Resources: Access dynamic content like personalized greetings
• Prompts: Generate contextual prompts for various interactions

Installation

Prerequisites

• Python 3.10 or higher
• uv package manager (recommended)

Setup

1. Clone or navigate to the project directory:

cd /Users/lotta/Documents/nibble_pixie_project/nibble_pixie_mcp_server

2. Install dependencies using uv:

uv sync

Or with pip:

pip install -e .

Usage

Running the Server

STDIO Transport (Default)

For local development and testing with MCP Inspector:

uv run nibble-pixie-server

Or directly with Python:

python src/nibble_pixie_mcp_server/server.py

SSE Transport

For Server-Sent Events transport:

uv run nibble-pixie-server --transport sse --host 127.0.0.1 --port 8000

Streamable HTTP Transport

For Streamable HTTP transport (recommended for production):

uv run nibble-pixie-server --transport streamable-http --host 127.0.0.1 --port 8000

Testing with MCP Inspector

Test your server using the MCP Inspector:

npx @modelcontextprotocol/inspector uv run nibble-pixie-server

Or with uv:

uv run mcp dev src/nibble_pixie_mcp_server/server.py

Installing in Claude Desktop

1. Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the server configuration:

{
  "mcpServers": {
    "nibble-pixie": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/lotta/Documents/nibble_pixie_project/nibble_pixie_mcp_server",
        "run",
        "nibble-pixie-server"
      ]
    }
  }
}

3. Restart Claude Desktop

Available Tools

Math Tools

All math tools are organized in the tools/math/ module.

add

Add two numbers together.

Parameters:

• a (int): First number
• b (int): Second number

Returns: Sum of the two numbers

subtract

Subtract two numbers.

Parameters:

• a (int): Number to subtract from
• b (int): Number to subtract

Returns: Difference of the two numbers

multiply

Multiply two numbers together.

Parameters:

• x (int): First number
• y (int): Second number

Returns: Product of the two numbers

divide

Divide two numbers.

Parameters:

• a (float): Dividend
• b (float): Divisor

Returns: Quotient of the two numbers

Available Resources

greeting://{name}

Get a personalized greeting.

Template Variables:

• name: The name to greet

Available Prompts

greet_user

Generate a greeting prompt.

Arguments:

• name (str): The name of the person to greet
• style (str, optional): The style of greeting (friendly, formal, casual). Default: "friendly"

Development

Project Structure

nibble_pixie_mcp_server/
├── .github/
│   └── copilot-instructions.md  # GitHub Copilot configuration
├── src/
│   └── nibble_pixie_mcp_server/
│       ├── __init__.py          # Package initialization
│       ├── server.py            # Main server implementation
│       └── tools/               # Modular tools directory
│           ├── __init__.py
│           └── math/            # Math tools module
│               └── __init__.py
├── pyproject.toml               # Project configuration
├── README.md                    # This file
├── STRUCTURE.md                 # Project structure guide
└── EXAMPLES.md                  # Usage examples

Adding New Features

Adding a Tool

Tools are organized by category in the tools/ directory. See for detailed instructions.

Quick example:

1. Create a new module: tools/your_category/__init__.py
2. Implement the tool function
3. Register it in server.py:

from .tools import your_category

@mcp.tool()
def your_tool(param: str) -> str:
    """Tool description."""
    return your_category.your_tool(param)

Adding a Resource

@mcp.resource("your-resource://{param}")
def your_resource(param: str) -> str:
    """Resource description."""
    # Your implementation
    return content

Adding a Prompt

@mcp.prompt()
def your_prompt(param: str) -> str:
    """Prompt description."""
    # Your implementation
    return prompt_text

Configuration Options

Command Line Options

• --transport: Transport protocol (stdio, sse, streamable-http). Default: stdio
• --host: Host to bind to for HTTP transports. Default: 127.0.0.1
• --port: Port to bind to for HTTP transports. Default: 8000
• --log-level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). Default: INFO

Troubleshooting

Server won't start

• Ensure Python 3.10+ is installed: python --version
• Verify dependencies are installed: uv sync
• Check for port conflicts if using HTTP transports

Claude Desktop can't find the server

• Verify the path in claude_desktop_config.json is absolute
• Make sure to restart Claude Desktop after configuration changes
• Check Claude's logs at ~/Library/Logs/Claude/mcp*.log (macOS)

Tools not appearing

• Ensure the server is running without errors
• Check the server logs for any initialization issues
• Verify the server configuration in Claude Desktop is correct

Resources

• MCP Documentation
• FastMCP Python SDK
• MCP Specification
• Example Servers

License

This project is created for the Nibble Pixie project.