A collection of standalone Python scripts that implement Model Context Protocol
(MCP) servers for various utility functions. Each server provides specialized
tools that can be used by AI assistants or other applications that support the
MCP protocol.
What is MCP?
The Model Context Protocol (MCP) is a standardized way for AI assistants to
interact with external tools and services. It allows AI models to extend their
capabilities by calling specialized functions provided by MCP servers.
Communication happens via standard input/output (stdio) using JSON messages.
Available Servers
Each MCP server is designed to be run using a Python environment manager like
uv.
A server that extracts information from YouTube videos using yt-dlp.
Tools:
- Extract Chapters: Get chapter information from a YouTube video.
- Extract Subtitles: Get subtitles from a YouTube video for specific
chapters or the entire video.
MCP Server Configuration:
"mcpServers": {
"ytdlp": {
"name": "youtube", // Optional friendly name for the client
"command": "uv",
"args": [
"run",
"--directory", "<path/to/repo>/useful-mcps/ytdlp", // Path to the MCP directory containing pyproject.toml
"--", // Separator before script arguments, if any
"ytdlp_mcp" // Match the script name defined in pyproject.toml [project.scripts]
]
// 'cwd' is not needed when using --directory
}
}
Word Document Processor (docx_replace)
A server for manipulating Word documents, including template processing and PDF
conversion.
Tools:
- Process Template: Replace placeholders in Word templates and manage
content blocks.
- Get Template Keys: Extract all replacement keys from a Word document
template.
- Convert to PDF: Convert a Word document (docx) to PDF format.
MCP Server Configuration:
"mcpServers": {
"docx_replace": {
"name": "docx", // Optional friendly name
"command": "uv",
"args": [
"run",
"--directory", "<path/to/repo>/useful-mcps/docx_replace", // Path to the MCP directory
"--",
"docx_replace_mcp" // Match the script name defined in pyproject.toml
]
}
}
PlantUML Renderer (plantuml)
A server for rendering PlantUML diagrams using a PlantUML server (often run via
Docker).
Tools:
- Render Diagram: Convert PlantUML text to diagram images (e.g., PNG).
MCP Server Configuration:
"mcpServers": {
"plantuml": {
"name": "plantuml", // Optional friendly name
"command": "uv",
"args": [
"run",
"--directory", "<path/to/repo>/useful-mcps/plantuml", // Path to the MCP directory
"--",
"plantuml_server" // Match the script name defined in pyproject.toml
]
}
}
(Note: Requires a running PlantUML server accessible, potentially managed via
Docker as implemented in the service).
Mermaid Renderer (mermaid)
A server for rendering Mermaid diagrams using the mermaidchart.com API.
Tools:
- Render Mermaid Chart: Convert Mermaid code into a PNG image by creating a
document on mermaidchart.com.
MCP Server Configuration:
"mcpServers": {
"mermaid": {
"name": "mermaid", // Optional friendly name
"command": "uv",
"args": [
"run",
"--directory", "<path/to/repo>/useful-mcps/mermaid", // Path to the MCP directory
"--",
"mermaid_mcp" // Match the script name defined in pyproject.toml
],
"env": { // Environment variables needed by the MCP
"MERMAID_CHART_ACCESS_TOKEN": "YOUR_API_TOKEN_HERE"
}
}
}
(Note: Requires a Mermaid Chart API access token set as an environment
variable).
A server for Convert rss feed content to markdown format with date filtering.
Tools:
- fetch_rss_to_markdown: Fetches an RSS feed, filters articles by date, and
returns matching articles formatted as a Markdown list..
MCP Server Configuration:
"mcpServers": {
"mermaid": {
"name": "rss2md", // Optional friendly name
"command": "uv",
"args": [
"run",
"--directory", "<path/to/repo>/useful-mcps/rss2md", // Path to the MCP directory
"--",
"rss2md_mcp" // Match the script name defined in pyproject.toml
],
"env": { // Environment variables needed by the MCP
}
}
}
Installation
- Clone the repository:
git clone https://github.com/daltonnyx/useful-mcps.git # Replace with the actual repo URL if different
cd useful-mcps
- Install
uv: If you don't have uv, install it:
pip install uv
# or follow instructions at https://github.com/astral-sh/uv
- Dependencies: Dependencies are managed per-MCP via
pyproject.toml.
uv run will typically handle installing them automatically in a virtual
environment when you run an MCP for the first time using --directory.
Usage
Running a Server
It's recommended to run each MCP server using uv run --directory <path>
pointing to the specific MCP's directory. uv handles the virtual environment
and dependencies based on the pyproject.toml found there.
Example (from the root useful-mcps directory):
# Run the YouTube MCP
uv run --directory ./ytdlp ytdlp_mcp
# Run the Mermaid MCP (ensure token is set in environment)
uv run --directory ./mermaid mermaid_mcp
Alternatively, configure your MCP client (like the example JSON configurations
above) to execute the uv run --directory ... command directly.
Connecting to a Server
Configure your MCP client application to launch the desired server using the
command and args structure shown in the "MCP Server Configuration" examples
for each server. Ensure the command points to your uv executable and the
args correctly specify --directory with the path to the MCP's folder and the
script name to run. Pass necessary environment variables (like API tokens) using
the env property.
These show example arguments you would send to the call_tool function of the
respective MCP server.
{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"language": "en",
"chapters": [
{
"title": "Introduction",
"start_time": "00:00:00",
"end_time": "00:01:30"
}
]
}
Word Document Processor
Process Template
{
"template_file": "/path/to/template.docx",
"replacements": {
"name": "John Doe",
"date": "2023-05-15"
},
"blocks": {
"optional_section": true,
"alternative_section": false
},
"output_filename": "/path/to/output.docx"
}
(Note: template_file and docx_file can also accept base64 encoded strings
instead of paths)
Get Template Keys
{
"template_file": "/path/to/template.docx"
}
Convert to PDF
{
"docx_file": "/path/to/document.docx",
"pdf_output": "/path/to/output.pdf"
}
PlantUML Renderer
Render Diagram
{
"input": "participant User
User -> Server: Request
Server --> User: Response",
"output_path": "/path/to/save/diagram.png"
}
(Note: input can also be a path to a .puml file)
Mermaid Renderer
Render Mermaid Chart
{
"mermaid_code": "graph TD;
A-->B;
A-->C;
B-->D;
C-->D;",
"output_path": "/path/to/save/mermaid.png",
"theme": "default" // Optional, e.g., "default", "dark", "neutral", "forest"
}
Development
Adding a New MCP Server
- Create a new directory for your MCP (e.g.,
my_new_mcp).
- Inside the directory, create:
pyproject.toml: Define project metadata, dependencies, and the script
entry point (e.g., [project.scripts] section mapping
my_new_mcp = "my_new_mcp:main").pyrightconfig.json: (Optional) For type checking.- Your main Python file (e.g.,
my_new_mcp.py): Implement the MCP logic
using the mcp library (see template below).
- Implement the required classes and functions (
serve, list_tools,
call_tool).
Basic template (my_new_mcp.py):
import json
import logging
import asyncio
from typing import List, Dict, Any, Optional
# Assuming mcp library is installed or available
# from mcp import Server, Tool, TextContent, stdio_server
# Placeholder imports if mcp library structure is different
from typing import Protocol # Using Protocol as placeholder
# Placeholder definitions if mcp library isn't directly importable here
class Tool(Protocol):
name: str
description: str
inputSchema: dict
class TextContent(Protocol):
type: str
text: str
class Server:
def __init__(self, name: str): pass
def list_tools(self): pass # Decorator
def call_tool(self): pass # Decorator
def create_initialization_options(self): pass
async def run(self, read_stream, write_stream, options): pass
# Placeholder context manager
class stdio_server:
async def __aenter__(self): return (None, None) # Dummy streams
async def __aexit__(self, exc_type, exc, tb): pass
# Pydantic is often used for schema definition
# from pydantic import BaseModel
# class MyInput(BaseModel):
# param1: str
# param2: int
class MyInputSchema: # Placeholder if not using Pydantic
@staticmethod
def model_json_schema():
return {"type": "object", "properties": {"param1": {"type": "string"}, "param2": {"type": "integer"}}, "required": ["param1", "param2"]}
class MyTools:
TOOL_NAME = "my.tool"
class MyService:
def __init__(self):
# Initialize resources if needed
pass
def my_function(self, param1: str, param2: int) -> dict:
# Implement your tool functionality
logging.info(f"Running my_function with {param1=}, {param2=}")
# Replace with actual logic
result_content = f"Result: processed {param1} and {param2}"
return {"content": result_content}
async def serve() -> None:
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
server = Server("mcp-my-service")
service = MyService()
@server.list_tools()
async def list_tools() -> list[Tool]:
logging.info("list_tools called")
return [
Tool(
name=MyTools.TOOL_NAME,
description="Description of my tool",
# Use Pydantic's schema or manually define
inputSchema=MyInputSchema.model_json_schema(),
),
]
@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
logging.info(f"call_tool called with {name=}, {arguments=}")
try:
if name == MyTools.TOOL_NAME:
# Add validation here if not using Pydantic
param1 = arguments.get("param1")
param2 = arguments.get("param2")
if param1 is None or param2 is None:
raise ValueError("Missing required arguments")
result = service.my_function(param1, int(param2)) # Ensure type conversion if needed
logging.info(f"Tool executed successfully: {result=}")
return [TextContent(type="text", text=json.dumps(result))] # Return JSON string
else:
logging.warning(f"Unknown tool requested: {name}")
raise ValueError(f"Unknown tool: {name}")
except Exception as e:
logging.error(f"Error executing tool {name}: {e}", exc_info=True)
# Return error as JSON
error_payload = json.dumps({"error": str(e)})
return [TextContent(type="text", text=error_payload)]
options = server.create_initialization_options()
logging.info("Starting MCP server...")
async with stdio_server() as (read_stream, write_stream):
await server.run(read_stream, write_stream, options)
logging.info("MCP server stopped.")
def main():
# Entry point defined in pyproject.toml `[project.scripts]`
try:
asyncio.run(serve())
except KeyboardInterrupt:
logging.info("Server interrupted by user.")
if __name__ == "__main__":
# Allows running directly via `python my_new_mcp.py` for debugging
main()
Testing
Run tests using pytest from the root directory:
pytest tests/
(Ensure test dependencies are installed, potentially via
uv pip install pytest or by adding pytest to the dev dependencies in one of
the pyproject.toml files).
License
MIT License
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.