Useful Model Context Protocol Servers (MCPS)

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.

YouTube Data Extractor (ytdlp)

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)._

Rss feed to markdown (rss2md)

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

1. Clone the repository:

   git clone https://github.com/daltonnyx/useful-mcps.git # Replace with the actual repo URL if different
   cd useful-mcps
   

2. Install uv: If you don't have uv, install it:

   pip install uv
   # or follow instructions at https://github.com/astral-sh/uv
   

3. 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.

Tool-Specific Usage Examples

These show example arguments you would send to the call_tool function of the
respective MCP server.

YouTube Data Extractor

Extract Chapters

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Extract Subtitles

{
  "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\nUser -> Server: Request\nServer --> 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;\n    A-->B;\n    A-->C;\n    B-->D;\n    C-->D;",
  "output_path": "/path/to/save/mermaid.png",
  "theme": "default" // Optional, e.g., "default", "dark", "neutral", "forest"
}

Development

Adding a New MCP Server

…