MCPixy 🚀

MCPixy is a zero-config MCP (Model Context Protocol) server builder for development or local work that allows you to create MCP servers with just YAML configuration. Connect any tool to your LLM in minutes without writing code.

✨ Features

🔧 Three Simple Tool Types

• CLI Tools ⚙️ - Execute commands, run scripts, access system utilities
• HTTP Tools 🌐 - Make API calls, handle authentication, manage web requests
• Web Scraping 🕷️ - Extract data from websites with CSS selectors

🛡️ Security & Trust

• Digital Signatures - Sign and verify tools for security
• Authentication - JWT-based auth with configurable modes
• Audit Logging - Track all tool usage and access
• Trusted Keys - Manage public keys for verified tools

🚀 Zero Configuration

• Bootstrap Setup - Get started with one command
• YAML Configuration - Define tools without coding
• Auto-discovery - Automatically load tools from directories

🚀 Quick Start

Prerequisites

• Rust 1.70+ (Install Rust)
• Git

Installation

# Clone the repository
git clone https://github.com/jondot/mcpixy.git
cd mcpgw

# Build the project
cargo build --release

# Bootstrap with default configuration
mcpixy bootstrap

Bootstrapping creates a default configuration, a sample tools file, and a key pair for signing tools in ~/.mcpixy.

The next time your run mcpixy it will all get picked up automatically.

First Tool

Edit your tools that were bootstrapped in ~/.mcpixy/tools/sample_tools.yaml, and add this for example:

tools:
  - id: http_get_example
    type: http
    name: "HTTP GET Example"
    description: "Simple GET request to any URL"
    method: GET
    url: "{{input.url}}"
    headers:
      User-Agent: "MCPixy/1.0"
    input_schema:
      type: object
      properties:
        url:
          type: string
          description: "URL to make GET request to"
      required: [url]

sign this tool:

mcpixy sign-tool --file ~/.mcpixy/tools/sample_tools.yaml --tool-id http_get_example

or sign all the tools:

mcpixy sign-tool --file ~/.mcpixy/tools/sample_tools.yaml

Configuring Cursor IDE

Add the following entry in your mcp.json:

{
  "mcpServers": {
    "mcpixy": {
      "url": "http://localhost:3033/mcp"
    }
  }
}

Remember if you ran your mcpixy normally, this will provide only signed tools, to allow unsigned tools run with mcpixy --allow-unsigned.

To use JWT auth, configure gateway.toml:

[auth]
mode = "jwt"
algorithm = "HS256"                   # or "RS256"
secret = "your-super-secret-key-here" # for HS256

Sign the JWT using the secret, and provide it through your mcp.json config:

{
  "mcpServers": {
    "mcpixy": {
      "url": "http://localhost:3033/mcp",
      "headers": {
        "Authorization": "Bearer eyJ...<REST OF TOKEN>"
      }
    }
  }
}

🛠️ CLI Commands

Core Commands

# Bootstrap with default configuration
mcpixy bootstrap

# Sign tools for security
mcpixy sign-tool --file tools.yaml --tool-id my_tool

# Verify tool signatures
mcpixy verify-tool --file tools.yaml --tool-id my_tool

Server Options

# Start with custom config
mcpixy --config my_config.toml

# Override port
mcpixy --port 8080

# Set log level
mcpixy --log-level debug

# Check configuration
mcpixy --check-config

🔐 Security Features

Digital Signatures

• Ed25519 key pairs for tool verification
• Public key management for trusted sources
• Signature verification before tool execution

Authentication Modes

• None - No authentication
• JWT - JSON Web Token authentication

Audit Logging

• Comprehensive logging of all tool executions
• User tracking and access monitoring
• Performance metrics and error reporting

🌐 Testing UI

Access the web UI at http://<your mcpixy address>/ui after starting the gateway:

• Tool Management - View, edit, and configure tools
• Real-time Monitoring - Watch tool execution live
• Configuration Editor - Visual YAML editing
• Usage Analytics - Performance and usage insights

🤝 Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.