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 FastMCPez-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:
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
Rename and customise:
cp ez-mcp.py my-awesome-server.py
Edit the server details (around line 160):
mcp = FastMCP( name="My Awesome Server", # <- Change this to your server name dependencies=["mcp>=1.9.0"] )
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}"
Run your server:
uv run my-awesome-server.py
For TypeScript/JavaScript Developers:
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
Rename and customise:
cp ez-mcp.ts my-awesome-server.ts chmod +x my-awesome-server.ts
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" });
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}` }] }) );
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
- π MCP Specification: https://modelcontextprotocol.io/
- π Python SDK Docs: https://github.com/modelcontextprotocol/python-sdk
- π TypeScript SDK Docs: https://github.com/modelcontextprotocol/typescript-sdk
- οΏ½ MCP Community: Join the discussions and get help
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