Official Substack MCP Server

🚀 Writing Context Tool for Claude

An open - source Model Context Protocol (MCP) implementation that connects Claude to your Substack and Medium writings.

🚀 Quick Start

The Writing Context Tool is an MCP server that enables Claude to access and analyze the articles you've published on Substack and Medium. With this tool, Claude can understand the context of your published content and offer more personalized writing assistance.

✨ Features

• 🔍 Retrieve and permanently cache your articles from Substack and Medium.
• 🔎 Use embedding technology to find the most relevant articles for your queries.
• 📚 Provide individual articles as separate resources to Claude.
• 🧠 Perform semantic searches within your works.
• ⚡ Pre - load all content and generate embeddings upon startup.

📦 Installation

Prerequisites

• Python 3.10 or higher.
• The latest version of Claude Desktop.
• A Substack or Medium account with published content.

1. Clone the repository

git clone https://github.com/yourusername/writer-context-tool.git
cd writer-context-tool

2. Set up the Python environment

Using uv (recommended):

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

Or using standard pip:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Configure your blog

1. Copy the example configuration file:

cp config.json.example config.json

2. Edit the values in config.json as needed, especially content_refresh_interval and embedding_model_choice.

4. Run the tool

Start the Writing Context Tool:

python run.py

💻 Usage Examples

Basic Usage

After installation, you'll see your personal articles as resources in Claude Desktop. You can perform the following actions:

1. Search your works: Ask Claude to find relevant content.

   • "Find articles discussing [specific topic]."
   • "What have I written about [topic]?"

2. Reference a single article: Access the full text by clicking on the article in the search results.

   • "Show the full text of [article title]."

3. Refresh content: Force a refresh of all content.

   • "Refresh my writing content."

📚 Documentation

How it works

The tool connects to your Substack/Medium blog via RSS feeds, fetches articles, and permanently caches them locally. It also generates embeddings for each article, enabling query - based semantic searches to find the most relevant articles.

When you ask Claude about your writing, it can use these single - article resources to provide insights or help you develop new ideas based on your existing content.

Available tools and resources

The Writing Context Tool provides:

1. Single - article resources: Each article becomes an optional resource.
2. search_writing: A semantic search tool that uses embeddings to find the most relevant articles.
3. refresh_content: Refresh and re - cache content on all configured platforms.

How caching works

The tool implements permanent caching with the following features:

1. Disk caching: All content is stored on disk, so it persists between sessions.
2. Embeddings: Each article is converted into an embedding for semantic search.
3. Selective refresh: The tool only refreshes the required content based on your caching settings.
4. Pre - loading: Automatically refreshes all content and generates embeddings upon startup.

Frequently Asked Questions

If you encounter issues:

1. The tool doesn't show up in Claude Desktop:

   • Check if your Claude Desktop configuration file is correct.
   • Ensure all paths in the configuration are absolute.
   • Make sure all required packages are installed in the Python environment.
   • Restart Claude Desktop.

2. No content is displayed:

   • Verify the Substack/Medium URLs in config.json.
   • Try using the "refresh_content" tool.
   • Check if your blog is public and has published articles.

3. uv command errors:

   • Try using the shell script method.
   • Confirm that the uv command is installed and in the PATH.

4. Embedding issues:

   • If you see errors related to the embedding model, ensure there is enough disk space.
   • Consider re - running for better results if the embeddings aren't working correctly.

📄 License

This project is available under the MIT License.