Jekyll MCP Server

# Jekyll MCP Server A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that indexes and searches Jekyll blog content, enabling AI assistants like Claude to interact with your blog posts. ## 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) ```bash uv pip install jekyll-mcp-server ``` ### Using pip ```bash pip install jekyll-mcp-server ``` ### From source ```bash git clone https://github.com/jottinger/jekyll-mcp-server.git cd jekyll-mcp-server uv pip install -e . ``` ## 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: ```bash 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: ```json { "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`): ```bash #!/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: ```bash 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 ```bash 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 ```bash 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](LICENSE) file for details. ## Contributing Contributions welcome! Please feel free to submit a Pull Request. ## Acknowledgments Built using the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic. Created with assistance from Claude Code.