Jekyll MCP Server

🚀 Jekyll MCP Server

A Model Context Protocol (MCP) server that indexes and searches Jekyll blog content, enabling AI assistants like Claude to interact with your blog posts.

🚀 Quick Start

The Jekyll MCP Server is a powerful tool that allows you to index and search your Jekyll blog content, making it accessible to AI assistants. Follow the steps below to get started.

✨ Features

• Index Jekyll blog posts and drafts with front matter parsing
• Search posts by keyword, category, or tags
• Retrieve full post content by slug
• Compare draft content against published posts to detect duplicates
• List all categories and tags with post counts
• Support for both Markdown (.md) and AsciiDoc (.adoc) formats
• Fast keyword-based search

📦 Installation

Using uv (recommended)

uv pip install jekyll-mcp-server

Using pip

pip install jekyll-mcp-server

From source

git clone https://github.com/jottinger/jekyll-mcp-server.git
cd jekyll-mcp-server
uv pip install -e .

📚 Documentation

Configuration

The server needs to know where your Jekyll blog content is located. There are two ways to configure this:

Option 1: Environment Variables

Set these environment variables before running the server:

export JEKYLL_POSTS_DIR="/path/to/your/blog/_posts"
export JEKYLL_DRAFTS_DIR="/path/to/your/blog/_drafts"  # Optional

Option 2: Run from Jekyll Project Directory

If you run the server from your Jekyll project root (where _posts and _drafts directories exist), it will automatically detect them.

Usage

With Claude Code

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "jekyll-blog": {
      "command": "jekyll-mcp-server",
      "env": {
        "JEKYLL_POSTS_DIR": "/path/to/your/blog/_posts",
        "JEKYLL_DRAFTS_DIR": "/path/to/your/blog/_drafts"
      }
    }
  }
}

Then restart Claude Code. The server will start automatically when needed.

Manual Launch

Create a launch script (see examples/launch-server.sh):

#!/bin/bash
export JEKYLL_POSTS_DIR="/path/to/your/blog/_posts"
export JEKYLL_DRAFTS_DIR="/path/to/your/blog/_drafts"
jekyll-mcp-server

Make it executable and run:

chmod +x launch-server.sh
./launch-server.sh

Available MCP Tools

Once connected, the server provides these tools to AI assistants:

search_posts

Search for blog posts by keyword, category, or tags.

Parameters:

• query (string, optional): Search term to find in title, content, or slug
• category (string, optional): Filter by category
• tags (string, optional): Comma-separated list of tags
• limit (number, optional): Maximum results (default: 10)

Example:

Search for posts about "AI writing" in the "blog" category

get_post

Retrieve full content of a specific post by slug.

Parameters:

• slug (string, required): The post slug

Example:

Get the post with slug "working-with-the-machine"

list_categories

List all blog categories with post counts.

Example:

Show me all categories

list_tags

List all blog tags with post counts.

Example:

What tags do I use?

compare_draft

Compare draft content against published posts to find similar content (helps avoid duplicate posts).

Parameters:

• draft_content (string, required): The draft text to compare
• limit (number, optional): Maximum similar posts to return (default: 5)

Example:

Compare this draft against my published posts:
[paste draft content]

Example Workflow

Here's how you might use this with Claude Code:

1. Before writing a new post:

   Search my posts for "AI writing process"
   

2. Check if you've covered a topic:

   Have I written about MCP servers before?
   

3. Prevent duplicate content:

   Compare this draft against my published posts:
   [paste draft]
   

4. Retrieve existing content:

   Get the full content of my post "working-with-the-machine"
   

5. Analyze your blog:

   What categories do I write about most?
   

Reindexing Content

The server indexes content on startup. After publishing new posts or making significant changes:

1. Stop the server (if running standalone)
2. Restart it to refresh the index

With Claude Code, the server restarts automatically when needed.

Development

Setup

git clone https://github.com/jottinger/jekyll-mcp-server.git
cd jekyll-mcp-server
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Running Tests

pytest

Project Structure

jekyll-mcp-server/
├── jekyll_mcp/
│   ├── __init__.py
│   ├── server.py       # MCP server implementation
│   ├── indexer.py      # Post indexing logic
│   ├── parser.py       # Front matter parsing
│   └── tools.py        # MCP tool implementations
├── examples/
│   ├── claude-code-config.json
│   └── launch-server.sh
├── tests/
├── LICENSE
├── README.md
└── pyproject.toml

Requirements

• Python 3.10 or higher
• Jekyll blog with standard _posts directory structure
• Posts with YAML front matter

📄 License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please feel free to submit a Pull Request.

Acknowledgments

Built using the Model Context Protocol by Anthropic.

Created with assistance from Claude Code.