{"_id":"@danielsimonjr/substack-mcp","_rev":"2-cfd75c5a804ffa155f995d8afc22163e","name":"@danielsimonjr/substack-mcp","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@danielsimonjr/substack-mcp","version":"1.0.0","keywords":["substack","api","client","typescript","mcp","model-context-protocol","claude","claude-desktop","claude-code","newsletter","automation"],"author":{"name":"Daniel Simon Jr."},"license":"MIT","_id":"@danielsimonjr/substack-mcp@1.0.0","maintainers":[{"name":"danielsimonjr","email":"danielsimonjr@yahoo.com"}],"homepage":"https://github.com/danielsimonjr/substack-mcp#readme","bugs":{"url":"https://github.com/danielsimonjr/substack-mcp/issues"},"bin":{"substack-mcp":"dist/mcp-server.js"},"dist":{"shasum":"405d238f3f3510342b4cc4fce71720d833378310","tarball":"https://registry.npmjs.org/@danielsimonjr/substack-mcp/-/substack-mcp-1.0.0.tgz","fileCount":77,"integrity":"sha512-CZVuP2pfyc+ACSZ07d9h9dGD8XGDH1BctqyLIDacF3k3Fme/N3+0UyXj2Xkj3Aw+DBH9mRUQkNQlD2HQjcbLMg==","signatures":[{"sig":"MEQCIEzDp1fPwMsRR+DluyiHuCHFuJRTpoz+dnbZrYU+cUJ3AiBZMZ9yYj0tx2gItNkrU8OtgYuwJf9jjrcJX1Wu6a4URw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":158627},"main":"dist/mcp-server.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"a37658ca61f9c96a217ba5f0fc13d90abe35bf6a","scripts":{"dev":"tsc && node dist/mcp-server.js","lint":"eslint . --ext .ts","test":"npm run test:unit && npm run test:integration && npm run test:e2e","build":"tsc","clean":"rm -rf dist","start":"node dist/mcp-server.js","format":"prettier --write \"src/**/*.ts\"","sample":"npx ts-node samples/index.ts","prepare":"npm run build","lint:fix":"eslint . --ext .ts --fix","test:all":"npm run test:unit && npm run test:integration && npm run test:e2e","test:e2e":"jest --config jest.e2e.config.js","test:unit":"jest","test:watch":"jest --watch","format:check":"prettier --check \"src/**/*.ts\"","test:e2e:watch":"jest --config jest.e2e.config.js --watch","test:integration":"jest --config jest.integration.config.js","test:integration:watch":"jest --config jest.integration.config.js --watch","_prepublishOnly_disabled":"npm test"},"_npmUser":{"name":"danielsimonjr","email":"danielsimonjr@yahoo.com"},"repository":{"url":"git+https://github.com/danielsimonjr/substack-mcp.git","type":"git"},"_npmVersion":"11.6.2","description":"MCP server for Substack API - interact with your Substack publication through Claude Desktop and Claude Code","directories":{},"_nodeVersion":"25.0.0","dependencies":{"fp-ts":"^2.16.10","io-ts":"^2.2.22","@modelcontextprotocol/sdk":"^1.20.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.0","dotenv":"^17.0.0","eslint":"^9.29.0","ts-jest":"^29.1.0","ts-node":"^10.9.2","prettier":"^3.5.3","@eslint/js":"^9.29.0","jest-junit":"^16.0.0","playwright":"^1.56.1","typescript":"^5.1.3","@types/jest":"^30.0.0","@types/node":"^24.0.3","eslint-plugin-prettier":"^5.5.0","@typescript-eslint/parser":"^8.34.1","@typescript-eslint/eslint-plugin":"^8.34.1"},"_npmOperationalInternal":{"tmp":"tmp/substack-mcp_1.0.0_1762399249874_0.055754250028993146","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@danielsimonjr/substack-mcp","version":"1.0.1","description":"MCP server for Substack API - interact with your Substack publication through Claude Desktop and Claude Code","main":"dist/mcp-server.js","types":"dist/index.d.ts","scripts":{"build":"tsc","start":"node dist/mcp-server.js","dev":"tsc && node dist/mcp-server.js","test":"npm run test:unit && npm run test:integration && npm run test:e2e","test:unit":"jest","test:integration":"jest --config jest.integration.config.js","test:e2e":"jest --config jest.e2e.config.js","test:watch":"jest --watch","test:integration:watch":"jest --config jest.integration.config.js --watch","test:e2e:watch":"jest --config jest.e2e.config.js --watch","test:all":"npm run test:unit && npm run test:integration && npm run test:e2e","prepare":"npm run build","test:ci":"npm run test:unit && npm run test:integration","prepublishOnly":"npm run build && npm run test:ci","clean":"rm -rf dist","lint":"eslint . --ext .ts","lint:fix":"eslint . --ext .ts --fix","format":"prettier --write \"src/**/*.ts\"","format:check":"prettier --check \"src/**/*.ts\"","sample":"npx ts-node samples/index.ts"},"bin":{"substack-mcp":"dist/mcp-server.js"},"repository":{"type":"git","url":"git+https://github.com/danielsimonjr/substack-mcp.git"},"keywords":["substack","api","client","typescript","mcp","model-context-protocol","claude","claude-desktop","claude-code","newsletter","automation"],"author":{"name":"Daniel Simon Jr."},"license":"MIT","bugs":{"url":"https://github.com/danielsimonjr/substack-mcp/issues"},"homepage":"https://github.com/danielsimonjr/substack-mcp#readme","devDependencies":{"@eslint/js":"^10.0.1","@types/jest":"^30.0.0","@types/node":"^26.0.1","@typescript-eslint/eslint-plugin":"^8.62.0","@typescript-eslint/parser":"^8.62.0","dotenv":"^17.0.0","eslint":"^10.4.1","eslint-plugin-prettier":"^5.5.0","jest":"^30.0.0","jest-junit":"^17.0.0","playwright":"^1.61.1","prettier":"^3.5.3","ts-jest":"^29.1.0","ts-node":"^10.9.2","typescript":"^6.0.3","uuid":"^14.0.1"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.30.0","fp-ts":"^2.16.10","io-ts":"^2.2.22"},"engines":{"node":">=18.0.0"},"overrides":{"ip-address":"^10.1.1","@babel/core":"^7.29.6","js-yaml":"^4.2.0"},"gitHead":"5e951c5a081e0307f1ea801ab986d60bf5466b9d","_id":"@danielsimonjr/substack-mcp@1.0.1","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-ARvjdBFTzRnPAZYmBTPjhVAiZA5MC7i5TTuz2KVHZ/r9fWb1twLlHjsq9bvBkjAx1PHP/Qb91bd8IoXaceepYQ==","shasum":"47cf5f968aacf694252bd32c4232e553075d6958","tarball":"https://registry.npmjs.org/@danielsimonjr/substack-mcp/-/substack-mcp-1.0.1.tgz","fileCount":73,"unpackedSize":148123,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD8kKkI1Dd7rwfDu2JTktEQXzKSJKwLVXnyCdbYQAIutgIhAOBCtyEqTcvq3W37Re98VW/obk/Cska/6ik7ZZs6PAa7"}]},"_npmUser":{"name":"danielsimonjr","email":"danielsimonjr@yahoo.com"},"directories":{},"maintainers":[{"name":"danielsimonjr","email":"danielsimonjr@yahoo.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/substack-mcp_1.0.1_1785723941732_0.5291809592507855"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-06T03:20:49.731Z","modified":"2026-08-03T02:25:42.005Z","1.0.0":"2025-11-06T03:20:50.062Z","1.0.1":"2026-08-03T02:25:41.873Z"},"bugs":{"url":"https://github.com/danielsimonjr/substack-mcp/issues"},"author":{"name":"Daniel Simon Jr."},"license":"MIT","homepage":"https://github.com/danielsimonjr/substack-mcp#readme","keywords":["substack","api","client","typescript","mcp","model-context-protocol","claude","claude-desktop","claude-code","newsletter","automation"],"repository":{"type":"git","url":"git+https://github.com/danielsimonjr/substack-mcp.git"},"description":"MCP server for Substack API - interact with your Substack publication through Claude Desktop and Claude Code","maintainers":[{"name":"danielsimonjr","email":"danielsimonjr@yahoo.com"}],"readme":"# Substack MCP Server\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n\nAn MCP (Model Context Protocol) server that allows Claude Desktop and Claude Code to interact with your Substack publication. Create posts with cover images, publish notes, manage your content, and more - all through natural conversation with Claude.\n\n## Features\n\n- ✅ **Post Management**: Create full blog posts with cover images\n- ✅ **Notes**: Create short-form Substack notes\n- ✅ **Profile Access**: Get your own profile and other users' profiles\n- ✅ **Content Retrieval**: Fetch posts, notes, and comments\n- ✅ **Image Upload**: Native Substack image upload (v2.3.0) - no third-party dependencies\n- ✅ **Draft Mode**: Create drafts for review before publishing\n\n## Version 2.3.0 - What's New\n\nThis version replaces Imgur with Substack's native image upload:\n- **Native Integration**: Direct upload to Substack's CDN (Amazon S3)\n- **Data URI Format**: Images encoded as base64 data URIs\n- **Automatic MIME Detection**: Supports PNG, JPG, JPEG, GIF, WEBP\n- **Post Association**: Images properly linked to posts via `postId`\n- **More Reliable**: No third-party API dependencies\n\n## Prerequisites\n\n- **Node.js 18+** installed on your system\n- **Substack account** with publication access\n- **Substack API Key** (connect.sid cookie value)\n\n## Getting Your Substack API Key\n\nThe Substack API uses cookie-based authentication:\n\n1. Login to Substack in your browser\n2. Open Developer Tools (F12 or Right-click → Inspect)\n3. Go to **Application/Storage** tab → **Cookies** → `https://substack.com`\n4. Find the `connect.sid` cookie and copy its value\n5. This value is your `SUBSTACK_API_KEY`\n\n⚠️ **Important**: Keep this cookie value private. Do not commit it to version control.\n\n### Cookie Extraction Tools\n\nThe `tools/` directory contains utility scripts to help extract your Substack cookie:\n- `extract-cookie.js` - Manual cookie extraction tool\n- `extract-cookie-auto.js` - Automated cookie extraction\n\nTo use these tools, save your cookie value to `tools/cookie.txt` (this file is git-ignored for security).\n\n## Installation\n\n### Building the MCP Server\n\n```bash\n# Clone or download this repository\ncd substack-mcp\n\n# Install dependencies\nnpm install\n\n# Build the TypeScript code\nnpm run build\n```\n\n### For Claude Desktop\n\n1. Open your Claude Desktop configuration file:\n   - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n2. Add the Substack MCP server configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"substack\": {\n      \"command\": \"node\",\n      \"args\": [\"C:\\\\Users\\\\YOUR_USER\\\\Dropbox\\\\Github\\\\substack-mcp\\\\dist\\\\mcp-server.js\"],\n      \"env\": {\n        \"SUBSTACK_API_KEY\": \"your-connect-sid-cookie-value-here\",\n        \"SUBSTACK_HOSTNAME\": \"yoursite.substack.com\"\n      }\n    }\n  }\n}\n```\n\n3. Replace `your-connect-sid-cookie-value-here` with your actual cookie value\n4. Replace `yoursite.substack.com` with your Substack hostname\n5. Restart Claude Desktop\n\n### For Claude Code\n\nAdd to your Claude Code MCP configuration or use:\n\n```bash\nclaude mcp add substack-mcp\n```\n\n## Available Tools\n\n### `mcp__substack__create_post`\nCreate a full blog post with optional cover image\n\n**Parameters:**\n- `title` (required): Post title\n- `body` (required): Post content (supports markdown)\n- `subtitle` (optional): Post subtitle\n- `cover_image` (optional): Path to cover image file\n- `draft` (optional): Create as draft (default: true)\n\n**Example:**\n```typescript\n{\n  title: \"My Amazing Post\",\n  body: \"This is the content of my post...\",\n  cover_image: \"c:/temp/cover-image.png\",\n  draft: true\n}\n```\n\n### `mcp__substack__create_note`\nCreate a new Substack note (short-form post)\n\n**Parameters:**\n- `text` (required): Note content\n\n### `mcp__substack__create_note_with_link`\nCreate a note with a link attachment\n\n**Parameters:**\n- `text` (required): Note content\n- `link` (required): URL to attach\n\n### `mcp__substack__get_own_profile`\nGet your own Substack profile information\n\n**Returns**: name, slug, handle, bio, follower count, photo URL\n\n### `mcp__substack__get_profile_posts`\nGet your recent posts\n\n**Parameters:**\n- `limit` (optional): Number of posts to retrieve (default: 10)\n\n### `mcp__substack__get_post`\nGet a specific post by ID with full content\n\n**Parameters:**\n- `post_id` (required): The post ID\n\n### `mcp__substack__get_post_comments`\nGet comments for a specific post\n\n**Parameters:**\n- `post_id` (required): The post ID\n- `limit` (optional): Number of comments (default: 20)\n\n### `mcp__substack__get_notes`\nGet your recent notes\n\n**Parameters:**\n- `limit` (optional): Number of notes (default: 10)\n\n## Usage Examples\n\n### With Claude Desktop/Code\n\nOnce configured, you can have natural conversations with Claude:\n\n```\n\"Create a new blog post titled 'Why I Love Programming' with this content...\"\n\n\"Create a draft post with the article from article.md and use cover.png as the cover image\"\n\n\"Get my recent posts from the last week\"\n\n\"Create a note saying 'New post just published!'\"\n```\n\nClaude will automatically use the appropriate MCP tools to fulfill your requests.\n\n## Environment Variables\n\n- `SUBSTACK_API_KEY` (required): Your connect.sid cookie value\n- `SUBSTACK_HOSTNAME` (required): Your Substack hostname (e.g., \"yourname.substack.com\")\n\n## Workflow Example\n\nHere's a typical workflow for creating a post with cover image:\n\n1. Write your article in markdown format\n2. Create or generate a cover image\n3. Tell Claude: \"Create a draft post with article.md and cover.png\"\n4. Claude will:\n   - Read the markdown file\n   - Upload the cover image to Substack's CDN\n   - Create the draft post with both\n   - Return the draft URL for review\n\n## Documentation\n\n- [CLAUDE.md](CLAUDE.md) - Development guidelines for Claude Code\n\n## Troubleshooting\n\n### \"SUBSTACK_API_KEY environment variable is required\"\nMake sure you've added the `SUBSTACK_API_KEY` to the `env` section of your MCP configuration.\n\n### \"Failed to connect\"\n1. Verify your connect.sid cookie value is correct and hasn't expired\n2. Check that you're logged into Substack in your browser\n3. Try getting a fresh cookie value by logging out and back in\n\n### MCP server not appearing in Claude Desktop\n1. Check that the path to `mcp-server.js` is correct\n2. Ensure Node.js 18+ is installed: `node --version`\n3. Run `npm run build` to compile the TypeScript\n4. Restart Claude Desktop after configuration changes\n\n### Image upload fails\n1. Ensure the image file exists and is readable\n2. Check that the file format is supported (PNG, JPG, JPEG, GIF, WEBP)\n3. Verify your Substack API key is valid\n\n## Development\n\nTo extend the MCP server:\n\n1. Edit `src/mcp-server.ts` to add new tools\n2. Run `npm run build` to compile TypeScript\n3. Restart Claude Desktop/Code to load changes\n\n### Testing\n\n```bash\nnpm test                  # Run all tests (unit + integration + e2e)\nnpm run test:unit         # Unit tests only\nnpm run test:integration  # Integration tests only\nnpm run test:e2e          # End-to-end tests\nnpm run lint              # Check code style\nnpm run format            # Format code\n```\n\n#### Running E2E tests against the real Substack API\n\nA strictly-gated E2E suite lives in `tests/e2e/substack-public-api.e2e.test.ts`.\nIt exercises the same public-read paths the MCP tools use (`profileForSlug`,\n`profile.posts()`, `postForId`, `post.comments()`) against a real publication.\n\n**The suite is skipped unless ALL three env vars are set** — this is an explicit\nopt-in to prevent accidental network calls in local or CI runs:\n\n| Variable                   | Required | Purpose                                                         |\n| -------------------------- | -------- | --------------------------------------------------------------- |\n| `SUBSTACK_API_KEY`         | yes      | `connect.sid` cookie value from an authenticated session        |\n| `SUBSTACK_E2E_PUBLICATION` | yes      | Publication slug (e.g. `platformer`) or hostname the suite reads against |\n| `SUBSTACK_E2E_ENABLED`     | yes      | Must be `1` — explicit kill-switch to prevent accidental runs   |\n\n```bash\n# One-shot (POSIX shell)\nSUBSTACK_E2E_ENABLED=1 \\\nSUBSTACK_API_KEY=... \\\nSUBSTACK_E2E_PUBLICATION=platformer \\\n  npm run test:e2e\n```\n\n> ⚠️ **Hits the real Substack API.** All assertions are read-only — the suite\n> does NOT publish, edit, or delete anything — but you will incur real HTTP\n> traffic against the configured publication. Use a publication you own or\n> have permission to read against.\n\nIf any of the three vars are missing, the suite registers a single skipped\ntest with the reason `set SUBSTACK_E2E_ENABLED=1 + SUBSTACK_API_KEY +\nSUBSTACK_E2E_PUBLICATION to run` and exits cleanly.\n\n## Security Notes\n\n- Never commit your connect.sid cookie value to version control\n- Store your API key securely using environment variables\n- The cookie value gives full access to your Substack account\n- Regularly refresh your cookie value for security\n\n## Version History\n\n- **v2.3.0** (Nov 2025): Native Substack image upload, replaces Imgur\n- **v2.2.0**: Added Imgur-based cover image upload\n- **v2.1.0**: Added create_post tool with ProseMirror support\n- **v2.0.0**: Initial MCP server implementation\n\n## Recent updates\n\nSee [CHANGELOG.md](CHANGELOG.md) for recent changes — gated E2E suite for the public Substack API.\n\n## License\n\nMIT - See LICENSE file for details\n\n## Credits\n\nBuilt on top of the [substack-api](https://github.com/jakub-k-slys/substack-api) TypeScript client.\n\nMCP server and image upload implementation by Daniel Simon Jr.\n","readmeFilename":"README.md"}