Processes Markdown files containing titles, body text, and tags for automated posting and draft saving to note.com
Note Post MCP
The Universal MCP Server exposes tools for automated posting and draft saving to note.com. It reads Markdown files containing titles, body text, and tags, then publishes them to your note.com account using Playwright automation.
Installation
Prerequisites
Node.js 18+
A note.com account
note-state.json
authentication state file (obtained via separate login script)Set
NOTE_POST_MCP_STATE_PATH
in your environment (optional, defaults to~/.note-state.json
)
Get an authentication state file
You need to obtain a
note-state.json
file containing your note.com authentication state.This can be generated using a Playwright login script that saves the browser's storage state after successful authentication.
Store this file securely and reference it via
NOTE_POST_MCP_STATE_PATH
or pass it as a parameter.
Install from GitHub
Or install from npm (if published)
Setup: Claude Code (CLI)
Use this one-liner (replace with your real values):
To remove:
Setup: Cursor
Create .cursor/mcp.json
in your client (do not commit it here):
Other Clients and Agents
Install via URI or CLI:
Add to your Claude Desktop configuration file (claude_desktop_config.json
):
Command:
npx
Args:
["note-post-mcp"]
Env:
NOTE_POST_MCP_STATE_PATH=/path/to/note-state.json
Type: STDIO
Command:
npx
Args:
note-post-mcp
Enabled: true
Example ~/.config/opencode/opencode.json
:
Add a new MCP and paste the standard JSON config from above.
Add the following to your Windsurf MCP configuration:
Setup: Codex (TOML)
Add the following to your Codex TOML configuration.
Example (Serena):
This server (minimal):
Configuration (Env)
NOTE_POST_MCP_STATE_PATH
: Path to the note.com authentication state file (default:~/.note-state.json
)NOTE_POST_MCP_TIMEOUT
: Timeout in milliseconds for browser operations (default:180000
)MCP_NAME
: Server name override (default:note-post-mcp
)
Available Tools
publish_note
Publishes an article to note.com from a Markdown file.
Inputs:
markdown_path
(string, required): Path to the Markdown file containing title, body, and tagsthumbnail_path
(string, optional): Path to the thumbnail image filestate_path
(string, optional): Path to the note.com authentication state filescreenshot_dir
(string, optional): Directory to save screenshotstimeout
(number, optional): Timeout in milliseconds
Outputs: JSON object with:
success
(boolean): Whether the operation succeededurl
(string): URL of the published articlescreenshot
(string): Path to the screenshotmessage
(string): Success message
save_draft
Saves a draft article to note.com from a Markdown file.
Inputs:
markdown_path
(string, required): Path to the Markdown file containing title, body, and tagsthumbnail_path
(string, optional): Path to the thumbnail image filestate_path
(string, optional): Path to the note.com authentication state filescreenshot_dir
(string, optional): Directory to save screenshotstimeout
(number, optional): Timeout in milliseconds
Outputs: JSON object with:
success
(boolean): Whether the operation succeededurl
(string): URL of the draft editor pagescreenshot
(string): Path to the screenshotmessage
(string): Success message
Markdown File Format
Your Markdown file should follow this format:
Alternatively, you can use array notation for tags:
Or use a simple #
heading for the title if no front matter is present:
Example invocation (MCP tool call)
For saving a draft:
Troubleshooting
Authentication errors: Ensure your
note-state.json
file is valid and up-to-date. You may need to regenerate it if your session has expired.Ensure Node 18+: Run
node -v
to verify your Node.js version.Build errors: Run
npm install
andnpm run build
to ensure all dependencies are installed and TypeScript is compiled.Local runs: After building, test locally with
npx note-post-mcp
(it will wait for MCP messages on stdin).Inspect publish artifacts: Run
npm pack --dry-run
to see what files will be included in the published package.Timeout issues: If operations are timing out, increase
NOTE_POST_MCP_TIMEOUT
or pass a largertimeout
parameter.Playwright browser not installed: Run
npx playwright install chromium
to install the required browser.
References
Name Consistency & Troubleshooting
Always use CANONICAL_ID (
note-post-mcp
) for identifiers and keys.Use CANONICAL_DISPLAY (
Note Post MCP
) only for UI labels.Do not mix different names across clients.
Consistency Matrix
npm package name →
note-post-mcp
Binary name →
note-post-mcp
MCP server name (SDK metadata) →
note-post-mcp
Env default MCP_NAME →
note-post-mcp
Client registry key →
note-post-mcp
UI label →
Note Post MCP
Conflict Cleanup
Remove any old entries with different names and re-add with
note-post-mcp
.Ensure global
.mcp.json
or client registries only usenote-post-mcp
for keys.Cursor: Configure in the UI only. This project does not include
.cursor/mcp.json
.
Example
Correct:
"mcpServers": { "note-post-mcp": { "command": "npx", "args": ["note-post-mcp"] } }
Incorrect: Using different keys like
"NotePost"
or"note_post"
(will conflict withnote-post-mcp
)
License
MIT
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables automated publishing and draft saving to note.com platform using Playwright automation. Reads Markdown files with titles, body text, and tags to publish content directly to your note.com account.