EZ MCP

πŸ‘‰ github.com/intellectronica/ez-mcp

Get an MCP server running in under 2 minutes! This repository contains complete, ready-to-run templates for single file self-contained MCP servers in both Python/uv and TypeScript/Deno.

πŸš€ Why EZ-MCP?

  • ⚑ Instant Setup: Copy, paste, run - no complex configuration needed
  • 🎯 Production Ready: Both templates use official Anthropic SDKs
  • πŸ“š Comprehensive Examples: Everything documented with working code
  • πŸ”§ Easily Extensible: Add your own tools, resources, and prompts in minutes
  • πŸ’‘ Perfect for Experimentation: The fastest way to test MCP ideas locally

πŸ“ What You Get

Two functionally identical, battle-tested templates:

  • ez-mcp.py - Python server using official MCP SDK with FastMCP
  • ez-mcp.ts - TypeScript server using official MCP SDK with Deno

Each template demonstrates all core MCP features:

  • πŸ“Š Resources: Dynamic data sources for LLM context
  • πŸ› οΈ Tools: Functions LLMs can call to perform actions
  • πŸ“ Prompts: Reusable templates for LLM interactions
  • βš™οΈ Configuration: Environment variable support

⚑ Quick Test Drive

Want to see these servers in action? Pick your language and run:

Python Version

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and run immediately
git clone <this-repo>
cd ez-mcp
uv run ez-mcp.py

TypeScript Version

# Install Deno (if not already installed)
curl -fsSL https://deno.land/install.sh | sh

# Clone and run immediately
git clone <this-repo>
cd ez-mcp
deno run --allow-all ez-mcp.ts

Both servers will start immediately and show you what’s available!

🎯 Create Your Own Server (Copy & Customise in 5 Minutes)

The fastest way to build your own MCP server is to copy one of our templates and customise it. Both templates are functionally identical and production-ready - just pick your preferred language!

For Python Developers:

  1. Copy the template:

    curl -O https://raw.githubusercontent.com/your-repo/ez-mcp/main/ez-mcp.py
# Or just copy the ez-mcp.py file contents from this repo

  2. Rename and customise:

    cp ez-mcp.py my-awesome-server.py

  3. Edit the server details (around line 160):

    mcp = FastMCP(
    name="My Awesome Server",  # <- Change this to your server name
    dependencies=["mcp>=1.9.0"]
)

  4. Add your own tools (copy this pattern anywhere in the file):

    @mcp.tool()
def my_custom_tool(input_text: str) -> str:
    """Describe what your tool does"""
    # Your logic here
    return f"Processed: {input_text}"

  5. Run your server:

    uv run my-awesome-server.py

For TypeScript/JavaScript Developers:

  1. Copy the template:

    curl -O https://raw.githubusercontent.com/your-repo/ez-mcp/main/ez-mcp.ts
# Or just copy the ez-mcp.ts file contents from this repo

  2. Rename and customise:

    cp ez-mcp.ts my-awesome-server.ts
chmod +x my-awesome-server.ts

  3. Edit the server details (around line 160):

    const server = new McpServer({
  name: "My Awesome Server",  // <- Change this to your server name
  version: "1.0.0"
});

  4. Add your own tools (copy this pattern anywhere in the file):

    server.tool(
  "my-custom-tool",
  { input_text: z.string() },
  async ({ input_text }) => ({
    content: [{ type: "text", text: `Processed: ${input_text}` }]
  })
);

  5. Run your server:

    deno run --allow-all my-awesome-server.ts

πŸŽ‰ That’s It!

You now have a working MCP server! The templates include extensive inline documentation and examples for adding:

  • Database connections (SQLite, PostgreSQL, etc.)
  • API integrations (REST APIs, GraphQL, etc.)
  • File operations (reading, writing, searching)
  • Web scraping
  • Environment variables and configuration
  • Error handling and validation

Just read through the template code - it’s designed to teach you everything you need to know!

οΏ½ Connect to MCP Clients

Once your server is running, connect it to any MCP client:

MCP Client Configuration

Add to your mcp.json file:

Python Server

{
  "mcpServers": {
    "my-python-server": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/your-server.py"],
      "env": {
        "MY_API_KEY": "your-key-here"
      }
    }
  }
}

TypeScript Server

{
  "mcpServers": {
    "my-typescript-server": {
      "command": "deno", 
      "args": ["run", "--allow-all", "/absolute/path/to/your-server.ts"],
      "env": {
        "MY_API_KEY": "your-key-here"
      }
    }
  }
}

πŸ› οΈ Development and Testing

Use MCP Inspector for Development

The MCP Inspector provides a web interface to test your server:

Python

# Install the inspector
pip install mcp

# Run with inspector
uv run mcp dev your-server.py

TypeScript

# Install the inspector
npm install -g @modelcontextprotocol/inspector

# Run with inspector  
npx @modelcontextprotocol/inspector deno run --allow-all your-server.ts

This opens a web interface where you can:

  • πŸ” Browse available tools, resources, and prompts
  • ▢️ Test tools with different parameters
  • πŸ“– View resource contents
  • πŸ§ͺ Experiment with prompts

Adding Dependencies

Python

Edit the dependencies section at the top of your .py file:

# dependencies = [
#   "mcp>=1.9.0",
#   "requests",     # For HTTP requests
#   "pandas",       # For data manipulation  
#   "sqlalchemy",   # For database access
# ]

TypeScript

Simply import what you need - Deno handles the rest:

import { parse } from "https://deno.land/std@0.224.0/csv/mod.ts";
import { serve } from "https://deno.land/std@0.224.0/http/server.ts";
import { DB } from "https://deno.land/x/sqlite@v3.8/mod.ts";

πŸ’‘ Real-World Examples

Quick File Search Tool

# Python
@mcp.tool()
def search_files(pattern: str, directory: str = ".") -> str:
    """Search for files matching a pattern"""
    import glob
    import os
    matches = glob.glob(os.path.join(directory, f"**/*{pattern}*"), recursive=True)
    return f"Found {len(matches)} files: {matches[:10]}"  # Show first 10
// TypeScript  
server.tool(
  "search-files",
  { pattern: z.string(), directory: z.string().default(".") },
  async ({ pattern, directory }) => {
    const matches = [];
    for await (const entry of Deno.readDir(directory)) {
      if (entry.name.includes(pattern)) {
        matches.push(entry.name);
      }
    }
    return {
      content: [{ type: "text", text: `Found files: ${matches.join(", ")}` }]
    };
  }
);

Web Scraper Tool

# Python (add "requests" to dependencies)
@mcp.tool()
async def scrape_url(url: str) -> str:
    """Scrape text content from a URL"""
    import httpx
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.text[:1000]  # First 1000 chars
// TypeScript
server.tool(
  "scrape-url", 
  { url: z.string() },
  async ({ url }) => {
    const response = await fetch(url);
    const text = await response.text();
    return {
      content: [{ type: "text", text: text.slice(0, 1000) }]
    };
  }
);

Database Query Tool

# Python (add "sqlite3" - built-in)
@mcp.tool()
def query_db(sql: str) -> str:
    """Execute a SQL query"""
    import sqlite3
    conn = sqlite3.connect("data.db")
    results = conn.execute(sql).fetchall()
    conn.close()
    return str(results)
// TypeScript
import { DB } from "https://deno.land/x/sqlite@v3.8/mod.ts";

const db = new DB("data.db");

server.tool(
  "query-db",
  { sql: z.string() },
  async ({ sql }) => {
    const results = db.queryEntries(sql);
    return {
      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
    };
  }
);

πŸ—οΈ Template Features Explained

Both templates include identical functionality to demonstrate all MCP capabilities:

πŸ“Š Resources (Data Sources)

  • server://info - Dynamic server information
  • Shows how to create data sources that LLMs can access
  • Perfect for configuration, documentation, or live data

πŸ› οΈ Tools (LLM Functions)

  • hello_someone (Python) / hello-someone (TypeScript)
  • Demonstrates parameter validation and environment variables
  • Template for any function you want LLMs to call

πŸ“ Prompts (Templates)

  • greeting_prompt (Python) / greeting-prompt (TypeScript)
  • Shows how to create reusable prompt templates
  • Perfect for complex instructions or workflows

βš™οΈ Configuration

  • Environment variable support (GREETING_PREFIX)
  • Error handling and input validation
  • Production-ready logging and startup messages

οΏ½ Common Use Cases

Perfect for:

  • πŸ§ͺ Rapid Prototyping: Test MCP ideas in minutes
  • πŸ”§ Personal Automation: Quick scripts for daily tasks
  • πŸ“Š Data Access: Connect LLMs to your databases/APIs
  • 🌐 Web Integration: Scrape sites, call APIs, process data
  • πŸ“ File Operations: Search, read, write, organise files
  • πŸ” Development Tools: Code analysis, documentation, testing
  • πŸ’Ό Business Logic: Custom workflows and integrations

πŸ“š Learn More & Get Help

Essential Resources

Deep Dive Into the Code

Both template files contain extensive inline documentation with:

  • Line-by-line explanations
  • Advanced usage patterns
  • Integration examples (databases, APIs, file systems)
  • Error handling best practices
  • Performance optimisation tips
  • Production deployment guidance

Read the source code - it’s designed to teach you everything you need to know!

🀝 Contributing & Feedback

Found these templates helpful? Have ideas for improvements? We’d love to hear from you!

  • πŸ› Report issues or suggest features
  • πŸ“ Share your cool MCP server creations
  • πŸ”§ Submit improvements to the templates
  • πŸ“š Help improve documentation

πŸ“œ License

MIT License - Use these templates however you want! See LICENSE file for details.

Β© Eleanor Berger β€” ai.intellectronica.net