Writer Blog Search (Substack & Medium) MCP server

This MCP server enables Claude to access and analyze your published content from Substack and Medium. The Writer Context Tool fetches your blog posts, caches them locally, and uses embeddings to find relevant essays based on your queries, allowing Claude to provide more personalized writing assistance.

Installation

Prerequisites

• Python 3.10 or higher
• Claude Desktop (latest version)
• A Substack or Medium account with published content

Setting Up the Environment

1. Clone the repository:

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

2. Set up Python environment (using uv):

   # Install uv if you don't have it
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Create 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
   

Configuration

1. Copy the example configuration file:

   cp config.example.json config.json
   

2. Edit config.json with your blog information:

   {
     "platforms": [
       {
         "type": "substack",
         "url": "https://yourusername.substack.com",
         "name": "My Substack Blog"
       },
       {
         "type": "medium",
         "url": "https://medium.com/@yourusername",
         "name": "My Medium Blog"
       }
     ],
     "max_posts": 100,
     "cache_duration_minutes": 10080,
     "similar_posts_count": 10
   }
   

Connecting with Claude Desktop

1. Create the Claude Desktop configuration directory:

   # On macOS
   mkdir -p ~/Library/Application\ Support/Claude/
   

2. Create the configuration file:

   # Get the absolute path to your uv command
   UV_PATH=$(which uv)
   
   # Create the configuration
   cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json << EOF
   {
     "mcpServers": {
       "writer-tool": {
         "command": "${UV_PATH}",
         "args": [
           "--directory",
           "$(pwd)",
           "run",
           "writer_tool.py"
         ]
       }
     }
   }
   EOF
   

   Alternative approach if you have issues with the uv command:

   # Make the script executable
   chmod +x run_writer_tool.sh
   
   # Update your Claude Desktop config
   cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json << EOF
   {
     "mcpServers": {
       "writer-tool": {
         "command": "$(pwd)/run_writer_tool.sh",
         "args": []
       }
     }
   }
   EOF
   

3. Restart Claude Desktop

Usage

Once the Writer Context Tool is set up, you can use it in Claude Desktop in several ways:

Searching Your Writing

Ask Claude to find relevant content across your published writing:

• "Find essays where I discuss artificial intelligence"
• "What have I written about climate change?"
• "Show me my articles about productivity"

Working with Specific Essays

When Claude shows search results, you can reference specific essays:

• "Show me the full text of [essay title]"
• "Analyze the structure of this essay"
• "Help me expand on the ideas in this article"

Refreshing Content

To update your cached content:

• "Refresh my writing content"

Available Tools

The Writer Context Tool provides these functionalities:

1. Individual Essay Resources - Each of your essays is accessible as a separate resource
2. search_writing - A semantic search tool that finds relevant essays using embeddings
3. refresh_content - Updates your content from all configured platforms

Troubleshooting

If you encounter problems:

• Tool doesn't appear in Claude Desktop:

  • Verify your configuration file has correct absolute paths
  • Ensure all required packages are installed
  • Restart Claude Desktop

• No content appears:

  • Check your blog URLs in config.json
  • Use the "refresh_content" tool
  • Verify your blogs are public with published posts

• Embedding issues:

  • Ensure you have sufficient disk space
  • Try reinstalling if embeddings don't work properly

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "writer-tool" '{"command":"uv","args":["--directory",".","run","writer_tool.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "writer-tool": {
            "command": "uv",
            "args": [
                "--directory",
                ".",
                "run",
                "writer_tool.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "writer-tool": {
            "command": "uv",
            "args": [
                "--directory",
                ".",
                "run",
                "writer_tool.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect