I Built an Open Source MCP To Analyze Your Substack Data With Hermes And Codex

A little while ago, I shared how I built a Substack API with Hermes and Codex and covered how a missing scheduling feature turned into the Unofficial Substack SDK. That article explained how I built the SDK, which was focused more on developers. Since then, I have added an MCP to it that runs directly on your computer.

This guide explains how to install and use it.

The premise was simple: I wanted Codex and Hermes (though it also works with Claude) to find my strongest posts, review my Notes, and run data analysis. The usual workaround involves copying figures from several Substack pages and pasting them into a chat, which was tedious.

So I added a read-only connection that lets Codex fetch the information it needs from Substack. You can install it without writing code, and the only technical part is copying a small settings block and adding your own publication details.

I’ll explain every step in plain English, including what the unfamiliar terms mean and where you need to be careful.

In This Edition

• What the Substack connection does

• How to add it to Codex safely

• How to confirm that you connected the right account

• Five prompts you can copy and adapt

What You’re Installing

You’ll configure an MCP server that runs exclusively on your computer and doesn’t rely on any external services. This means your data will only be shared between your Substack profile and your AI, so nobody else can see it.

Moreover, the connection is read-only. It can look at your profile, posts, Notes, subscriber totals, and recent activity. I specifically left out every action that would change your account, so Codex can’t publish, delete, comment, restack, or change your settings through this MCP.

The GitHub project also contains an SDK, which is a toolkit for developers who want to build their own software. You won’t use that part in this guide, and please make sure you know what you’re doing if you feel like you want to access the full capabilities of this project.

What You Need

The setup requires three items:

• Node.js 18 or newer: This free program lets your computer run the MCP.

• Your publication address: For example yourname.substack.com.

• Your Substack session cookie: A private login value stored by your browser.

The word “cookie” sounds harmless, but this one proves that you’re logged in. Anyone who gets it may be able to access your account.

Treat it like your password.

Check Node.js

Open Terminal on macOS or Windows Terminal on Windows. Paste this command and press Enter:

node --version

If you see a version beginning with v18 or a higher number, continue. If the command isn’t recognised, install the current supported version of Node.js from its official website, then run the check again.

You can close the terminal after this check as the rest of the setup happens in a Codex settings file.

Find Your Login Cookie

Start by logging in to Substack in your browser.

You can get it super easily by installing the EditThisCookie (V3)Chrome extension and copying the value of substack.sid=.

If you don’t want that then you must use your browser’s developer tools. On Windows and Linux, the usual shortcut is Ctrl+Shift+I. On macOS, use Cmd+Option+I, or just press F12 on your keyboard. The shortcut or tab name can vary slightly between browsers.

Look for a tab named Application or Storage, then open the cookie list for Substack. Find the row named substack.sid and copy the value column.

Copy the long value alone. Leave out substack.sid= and any other cookie entries.

I can’t stress this enough but you HAVE to keep this value private. It shouldn’t appear in a public prompt, screenshot, shared project folder, support ticket, or shared document.

Add It To Codex

There are 2 ways to do this. First, just go to Plugins, then click on the gear icon up top Manage, then click on MCPs and Add Server.

Complete it like this:

Name: substack  
Type: STDIO  
  
Command to launch:  
npx  
  
Arguments:  
-y  
unofficial-substack-sdk  
  
Environment variables:  
SUBSTACK_SESSION_TOKEN = eyJ...  
SUBSTACK_PUBLICATION_URL = yoursubstack.substack.com

Then just save and restart Codex. Everything should work once you open it up again.

The second way to install the MCP is a bit more complicated and manual. Codex keeps its personal settings in a file named config.toml.

On macOS and Linux, the usual location is:

~/.codex/config.toml

On Windows, it sits inside your user folder:

C:\Users\YOUR-NAME\.codex\config.toml

Folders whose names begin with a dot are sometimes hidden. On Windows, open File Explorer and paste the full path into the address bar after replacing YOUR-NAME. On macOS, open Finder, choose Go, then Go to Folder, and enter ~/.codex.

Open config.toml in a plain text editor such as Notepad or TextEdit. Create it if it doesn’t exist. If the file already contains settings, keep them and paste the block below at the end:

[mcp_servers.substack]
command = "npx"
args = ["-y", "unofficial-substack-sdk"]

[mcp_servers.substack.env]
SUBSTACK_SESSION_TOKEN = "your-substack.sid-value"
SUBSTACK_PUBLICATION_URL = "https://your-publication.substack.com"

You don’t need to understand the formatting. Change only the two values inside quotation marks at the bottom.

Replace your-substack.sid-value with the private cookie value you copied. Replace the example publication address with your real Substack address, including https://.

If the file already has a section beginning with [mcp_servers.substack], edit that section instead of adding a second copy. When creating the file in Notepad, check that it ends in .toml rather than .toml.txt.

Use the personal settings file for this connection. Settings kept inside a project can accidentally be copied or uploaded with the rest of its files, which creates an unnecessary risk for the cookie.

Save the file and restart Codex. The Codex desktop app, command-line app, and editor extension use the same MCP settings on the same computer, according to the official Codex MCP documentation.

The first request may take a little longer because npx, a helper installed with Node.js, downloads the MCP package before starting it. You don’t need to open the package or install a separate Substack app.

Check The Connection

Begin with a small request. This confirms the account before Codex pulls a larger set of publication statistics.

Paste this prompt:

Use my Substack MCP to confirm which account is connected and list my five most recent posts with their publication dates.

Stop after the list. Say so if the account or publication doesn't match.

Check the account name and post titles yourself. These three messages cover the most common setup problems:

• The wrong publication appears: Correct the publication address in config.toml.

• You see a login error: The cookie has probably expired or was copied incorrectly. Log in to Substack again, copy a fresh substack.sid value, and replace the old one.

• Codex couldn’t start the MCP: Repeat the Node.js check from the earlier section.

Restart Codex after every change to the settings file.

Ask A Focused Question

A broad request such as “analyze my Substack” gives Codex too much freedom. It has to guess the period, the measurement that matters, and the kind of answer you want.

Your prompt should make four choices clear:

• The goal: State the decision you’re trying to make.

• The material: Name the post, Note, or period you want reviewed.

• The limit: Ask for a short summary before requesting detailed records.

• The standard: Tell Codex to label facts and guesses separately.

You can refer to an article by title instead of hunting for the behind-the-scenes number Substack assigned to it. Ask Codex to find the title first, confirm the match, and then inspect it.

Five Prompts Worth Saving

These prompts use normal language. Codex chooses the appropriate Substack tools behind the scenes.

Text inside square brackets is a blank for you to replace. For example, change [POST TITLE] to the exact title of your article. You can also change quantities such as “top 10” or “20 most recent” without touching your settings.

Review Your Publication

Use this when you want a broad view of what happened during a month or quarter.

Use my Substack MCP to review my publication from [START DATE] through [END DATE].

Rank the top 10 posts by new subscribers. Summarize the totals and average rates that Substack provides, then group the posts by section and content type.

Keep the detailed post rows out of the response. Separate the numbers Substack returned from your interpretation, then suggest two ideas I can test next month.

Review One Post

You can use the post title here. Codex can find its behind-the-scenes number for you.

Find the Substack post titled “[POST TITLE]” and confirm the title and date before analyzing it.

Summarize the available delivery, subscriber, link, referral, and reader-engagement figures. Point out anything Substack didn't provide instead of estimating it.

Give me two strengths, two weak points, and one follow-up question. Keep reported facts separate from your interpretation.

Compare Your Notes

Substack doesn’t always provide a reliable view count for Notes. This prompt uses visible reactions and conversations instead.

Use my Substack MCP to review my 20 most recent Notes.

Choose five Notes with the strongest visible response, then compare their reactions, restacks, direct replies, and replies inside those conversations.

Tell me if any reply count is incomplete. Don't rank the Notes by views unless Substack supplied a real view number.

Sort Your Notifications

This prompt asks Codex to prepare a shortlist. The read-only MCP can’t send the replies.

Use my Substack MCP to check my 20 most recent unread activity items.

Put replies and mentions ahead of restacks and lower-priority activity. Choose the five items that most deserve my attention.

Summarize the context and suggest one response angle for each. Leave every reply as a draft for my review.

Check Subscriber Totals

This prompt keeps individual subscriber records out of the conversation.

Use my Substack MCP to return a privacy-safe subscriber summary.

Show the total subscriber count and any overall figures Substack provides. Don't request names, email addresses, or individual subscriber records.

Explain what this snapshot tells me and where the available information stops. Don't calculate growth or churn unless Substack returned the history required for that calculation.

Ask For Summaries First

Codex has a limited amount of working memory in each conversation. Large blocks of raw data occupy space that the model could use to compare results and explain them.

Think of that working memory as a desk. A neat summary leaves room to reason. Hundreds of copied rows cover the desk before the useful work begins.

The MCP already reduces many responses before returning them. A publication review can read the email data Substack makes available while sending Codex a compact summary. Detailed rows stay out unless you request them.

Follow the same habit in your prompts. Start with a summary, choose the one post or Note that deserves attention, then ask a narrower follow-up question.

What Read-Only Protects

The MCP leaves every account-changing action unavailable. A mistaken prompt can’t publish a Note or delete a comment through this connection.

But read-only access still requires care. Your cookie opens the connection, and the information Codex receives becomes part of the conversation. Keep the cookie in your personal settings file and leave individual subscriber records out of your requests.

This project connects through parts of Substack’s website that aren’t documented for outside apps. Substack can change them without warning, meaning that a request that worked yesterday might fail today. If that’s the case then you might want to check the GitHub project page for an update or reported problem.

People building custom software can use the developer toolkit for Note publishing and other account actions. That route requires code, testing, and a human approval step. The read-only MCP is the better fit when you want to ask questions about your publication.

Your First Ten Minutes

Use this sequence:

1. Check that Node.js 18 or newer is installed.

2. Copy the value of your substack.sid cookie.

3. Paste the settings block into your personal Codex settings file.

4. Restart Codex and run the account-check prompt.

5. Choose one focused prompt from this guide.

Check important figures against your Substack dashboard while you learn how the connection behaves. Save the prompts that help, while keeping the private answers out of public screenshots and repositories.

The MCP finds the information. You decide what it means and what deserves to change.

What Should I Add Next?

I’m continuing to expand the read-only Substack tools around questions publishers still answer by hand.

What’s the most frustrating analytics question you still have to answer inside the Substack dashboard? Leave it in the comments, and I’ll use the replies to guide the next tool or tutorial.

You can find the public project on GitHub and its installation package on npm.

Everything I described here is one small example of the broader pattern behind the first Hermes 101 course: connect an agent to the tools and information you control, keep the sensitive parts local, and build a workflow you can inspect. I’m working on the course right now, and it should be ready soon. If you want the full step-by-step Hermes setup, that course is where it will live.