Substack for Claude

This lets Claude write drafts in your Substack for you.

You talk to Claude. Claude writes the draft. The draft appears in your Substack. You read it, and if you like it, you press Publish.

Claude can never publish anything or email your readers. Only you can do that.

Once it's set up, you can ask Claude things like:

• "Turn these notes into a Substack draft."

• "Rewrite the start of my latest draft."

• "What have I written about pricing?"

Setup guide

Setup takes about 20 minutes. Do the parts in order and don't skip any.

Before you start: what you need

• A Mac. This doesn't work on Windows.

• The Claude desktop app, installed and signed in. Get it from claude.ai/download. (The website and phone app can't use this. See Part 7.)

• Google Chrome or Microsoft Edge. Safari won't work for one step. Both are free.

• A Substack account you can sign in to. The email sign-in link is fine. You don't need a password.

• The internet.

Related MCP server: Substack MCP Server

How to read these steps

• "Click" means press the left side of your mouse or trackpad once.

• "Press Enter" means press the big key on the right of your keyboard marked return or Enter.

• "Cmd" is the key marked ⌘ command, on either side of the space bar.

• "Cmd + Space" means hold down Cmd, press Space once, then let go of both.

• When a step says "Type", type exactly what it shows, letter for letter.

• To paste a line into Terminal, copy it from this page, click inside Terminal, press Cmd + V, then press Enter. Paste one grey box at a time.

Part 1: Install Node.js

Node.js is a free program this needs to run. You only do this once.

1. Open your web browser.

2. Click in the address bar at the top, type nodejs.org, and press Enter.

3. Click the big green button that says LTS. A file downloads.

4. Open your Downloads folder. One way is to click the Finder icon (the blue smiling face) at the bottom of your screen, then click Downloads on the left.

5. Double-click the file that starts with node and ends in .pkg.

6. A window opens. Click Continue on each screen, then Agree, then Install.

7. If your Mac asks for your password, type the password you use to unlock your Mac and press Enter. Nothing appears as you type it. That's normal.

8. When it says The installation was successful, click Close.

Part 2: Open Terminal

Terminal is a window where you type instructions to your Mac. It looks plain, but it's safe to use if you follow these steps exactly.

1. Press Cmd + Space. A search bar appears in the middle of your screen.

2. Type Terminal.

3. Press Enter.

A white or black window opens with some text and a blinking line. That's Terminal. Keep it open for the rest of the setup.

Part 3: Download this project

1. Paste this into Terminal and press Enter:

   git clone https://github.com/Philm-moxywolf/Substack-MCP.git ~/substack-mcp

If a box pops up asking to install "command line developer tools": click Install, then Agree, and wait for it to finish. It can take 5 to 20 minutes. When it's done, click inside Terminal, press Cmd + V and Enter again.

You'll know it worked when Terminal shows a few lines that say Cloning into and then goes quiet. You now have a folder called substack-mcp in your home folder.

Part 4: Add the Substack Key Grabber to your browser

Claude needs a key that proves to Substack it's you. Your browser already has it, because you sign in to Substack there. This small add-on hands it over in one click. You only add it once.

Do this in Chrome or Edge:

1. Click the address bar, type the line for your browser, and press Enter:

   • Chrome: chrome://extensions

   • Edge: edge://extensions

2. Turn on Developer mode. It's a switch at the top right in Chrome, or on the left side in Edge.

3. Click Load unpacked. A window opens to pick a folder.

4. Press Cmd + Shift + H to jump to your home folder. Double-click substack-mcp, click once on extension, then click Select.

5. Substack Key Grabber now shows in the list.

6. Pin it so it's easy to find. Click the puzzle piece icon at the top right of the browser, then click the pin next to Substack Key Grabber. A small S icon appears in the toolbar.

7. In the same browser, go to substack.com and sign in if you aren't already. Use the email link if that's how you normally sign in.

Leave the browser open and go back to Terminal.

Part 5: Run the setup

1. Paste this into Terminal and press Enter. Nothing seems to happen. That's correct.

   cd ~/substack-mcp

2. Paste this into Terminal and press Enter:

   ./install.sh

3. Terminal says 1 of 4: Building... Wait. This can take a minute or two.

4. Terminal says 2 of 4: Your Substack and waits. Type the first part of your Substack address, then press Enter.

   • If your Substack is janesmith.substack.com, type janesmith.

   • Not sure? Open your Substack in the browser and look at the address bar.

   • If you use your own web address, like news.janesmith.com, type that instead.

5. Terminal says 3 of 4: Your Substack key and asks Use the browser add-on? [Y/n]. Press Enter.

6. Terminal says Ready. Now click the Substack Key Grabber button in your browser.

7. Go to your browser. Click the S icon in the toolbar, then click Grab my Substack key.

8. The add-on says Saved! Back in Terminal, it says Substack accepted your key. You have 5 minutes to click. If you miss it, just do step 2 again.

9. Terminal says 4 of 4: Connecting to Claude, then Connected, then All done.

Part 6: Start using it

1. Click on the Claude app.

2. Press Cmd + Q to quit it completely. (Closing the window isn't enough.)

3. Open Claude again.

4. Start a new chat, type this and press Enter: List my Substack drafts

5. The first time, Claude asks permission to use a Substack tool. Click Allow (or Always allow, so it stops asking).

If Claude shows your drafts, everything works. If you have no drafts yet, it may say there aren't any, which is fine too.

You can close Terminal now. Don't move or delete the substack-mcp folder in your home folder. Claude needs it to stay where it is.

Part 7: Use it in a Claude Project

A Project is a space in Claude with its own instructions and files. Set one up for your newsletter and Claude will remember your voice and your rules in every chat inside it.

Where it works: in the Claude desktop app on the Mac where you ran the setup, in normal chats and in Projects. It does not work on the claude.ai website, the phone app, or another computer, because it runs on your Mac. Your Mac needs to be on and the Claude app open.

Set up the Project (once)

1. In the Claude desktop app, click Projects in the left sidebar.

2. Click New project. Name it something like My Substack and create it.

3. Find the project's instructions box and paste the text below into it. Change the first line to your newsletter's name.

   You help me write my Substack newsletter, [YOUR NEWSLETTER NAME].
   
   Tools: you have Substack tools. Use them, don't guess.
   - To learn my voice, use search_posts and get_post to read 2–3 of my published posts on a related topic before you draft.
   - Save every piece as a Substack draft with create_draft, then give me the editUrl.
   - To change an existing draft, use get_draft first, then update_draft with the complete new body (update_draft replaces the whole body).
   - Write the body in Markdown: short paragraphs, ## headings, bullet lists and links. Don't repeat the title in the body.
   - Audience is "everyone" unless I say otherwise ("only_paid", "only_free" or "founding").
   
   Rules:
   - You can't publish or email anyone. Never say a post is published or sent. I review the draft in Substack and press Publish myself.
   - Never put anything from my Substack key or settings into a chat.

4. Optional: add files that help, such as a style guide, your About page, or a few of your favourite posts.

Use it

Open the Project and start a chat inside it. For example:

• "Here are my notes from today's call. Turn them into a draft post called 'What I learned about pricing'."

• "Read my last three posts and tell me which topics I keep coming back to."

• "Open my latest draft and tighten the first two paragraphs."

Claude saves the draft and gives you a link. Open it in Substack, read it, edit anything you like, and press Publish when you're happy.

Can't see the Substack tools in a chat? In the message box, open the tools menu (the button next to where you type) and check substack is switched on. If it isn't listed at all, quit Claude with Cmd + Q and open it again.

Keep your key secret

The setup saves a key that lets this act as you on Substack. It's like the key to your house.

• It's stored safely in your Mac's Keychain, where your Mac keeps passwords. The add-on only ever sends it to your own Mac.

• Never send it to anyone, paste it into a chat, or share a screenshot of it. That includes the person who sent you this guide.

• If you think someone has seen it, sign out of Substack on every device. That makes the old key stop working. Then sign in again and refresh your key (below).

Refresh your key

Substack signs you out every so often, and then Claude says it can't reach your drafts. Getting a fresh key takes about 30 seconds:

1. In Chrome or Edge, sign in to Substack again.

2. Open Terminal (Part 2), paste this and press Enter:

   cd ~/substack-mcp && npm run grab:ext

3. When it says Ready, click the S icon, then Grab my Substack key.

4. Terminal says Got it. Quit Claude with Cmd + Q and open it again.

If something goes wrong

Terminal says "Node.js is missing" Do Part 1 again. Then close Terminal, open it again (Part 2), and continue from Part 5.

Terminal says "command not found" or "No such file or directory" Something got skipped or mistyped. Copy and paste each line again rather than typing it. If you see quote>, press Control + C and paste the line again.

Terminal says "couldn't find a Substack" Your Substack name was typed wrong. Do Part 5 again and check the name.

The add-on says "Couldn't find your Substack sign-in key" You're not signed in to Substack in that browser. Sign in at substack.com, reload the page, then click the add-on again.

The add-on says "Couldn't reach the setup on your Mac" Terminal isn't waiting for it. Do Part 5 again (or "Refresh your key"), wait for Ready, then click.

Terminal says "Something is already using port 8789" An earlier setup window is still waiting. Close the other Terminal window, or press Control + C in it, then try again.

Terminal says "Substack refused" You may be signed in to a different Substack account than the name you typed. Check both, then do Part 5 again.

Claude can't see your drafts Quit Claude with Cmd + Q and open it again. Your Mac needs to be on, because this runs on your computer. If it worked before, your key has probably run out: see "Refresh your key".

Terminal says "The Claude app isn't installed yet" Install the Claude desktop app from claude.ai/download, open it once and sign in, then do Part 5 again. When it asks about your saved key, press Enter to keep it.

"Too many requests" Substack wants you to slow down. Wait an hour and try again.

Get your key by hand

Only use this if the add-on doesn't work for you. It works in Chrome and Edge.

1. In Chrome or Edge, sign in to Substack.

2. Click the address bar, type yourname.substack.com/publish/posts (using your Substack name) and press Enter.

3. In the menu bar at the very top of your screen, click View, then Developer, then Developer Tools. A panel opens.

4. In the row of words at the top of that panel, click Network. If you can't see it, click >> at the end of the row, then Network.

5. Just below, click Fetch/XHR.

6. Press Cmd + R. A list of rows appears.

7. Click any row that shows 200 in the Status column.

8. On the right, click Headers, then scroll down to Request Headers.

9. Find the long line called Cookie. Look in it for substack.sid=. If it isn't there, look for connect.sid=.

10. Select only the part after the =, up to but not including the next ;. It starts with s%3A. Right-click it and choose Copy.

11. In Terminal, paste this and press Enter:

    cd ~/substack-mcp && npm run paste-key

12. When it asks, press Cmd + V, then Enter. Nothing shows as you paste. That's normal. It checks the key with Substack before saving it, and says Saved.

13. If you haven't run the setup yet, do Part 5 now. When it asks about your saved key, press Enter to keep it.

For the technically curious

This is unofficial. Substack has no public way to write drafts, so this uses the same private route Substack's own website uses, signed in as you. It could stop working if Substack changes its website. You use it at your own risk, on your own account.

• It's a local MCP server that Claude starts over stdio. Your key never leaves your Mac except in requests to Substack.

• Your key is stored in macOS Keychain (service substack-mcp, account substack.sid), never in a file.

• Your Substack name is stored in ~/.config/substack-mcp/config.json.

• The installer adds a substack entry under mcpServers in Claude's desktop config and in ~/.claude.json (Claude Code), keeping a backup ending in .bak-substack. Pass --no-connect to skip this.

• Why an add-on: Substack's session cookie is httpOnly and held in the browser's memory (partitioned), so it isn't in the cookie files on disk. The add-on reads it through the browser's cookies API and posts it to a listener on 127.0.0.1:8789 (npm run grab:ext), which only saves it if Substack confirms it's a signed-in session.

• npm run grab opens a fresh sign-in window instead. It only works for accounts with a Substack password, because Substack won't send a sign-in link to an automated browser.

Remove it

1. Delete the substack-mcp folder in your home folder, and the folder ~/.config/substack-mcp.

2. Paste this into Terminal and press Enter, to remove your key from Keychain:

   security delete-generic-password -s substack-mcp -a substack.sid

3. In Chrome or Edge, go to chrome://extensions or edge://extensions and click Remove on Substack Key Grabber.

4. To disconnect Claude, remove the substack entry under mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json and in ~/.claude.json.