note-mcp-community

Unofficial, community-maintained stdio MCP server for note.com. It uses cookie-based access to note.com's internal APIs.

Quick start

Local/desktop agents

Use browser login first:

npx note-mcp-community auth

After you log in to note.com in the opened browser, note-mcp-community saves the cookie locally and prints the saved file path:

{
  "authenticated": true,
  "saved": true,
  "configPath": "/Users/you/.config/note-mcp-community/config.json",
  "cookiePreview": "fp=b…5948",
  "message": "note.com authentication configured from browser login. Cookie saved to /Users/you/.config/note-mcp-community/config.json."
}

Then configure your MCP client without putting cookies in the config:

{
  "mcpServers": {
    "note": {
      "command": "npx",
      "args": ["-y", "note-mcp-community"]
    }
  }
}

Some MCP clients only load newly added tools when a process or conversation starts. After authentication or config changes, restart the client or open a new thread/session if note_* tools do not appear immediately.

Quick setup check:

1. npx note-mcp-community auth

2. npx note-mcp-community auth --status

3. Add npx -y note-mcp-community to your MCP client config

4. Restart the client or open a new thread/session

5. Run note_auth_status from the MCP client

Servers, containers, and CI

Do not rely on browser login in headless/container environments. Provide a cookie through env or a mounted config file instead:

NOTE_COOKIE='your note.com Cookie header' npx note-mcp-community

Or mount a config file and point NOTE_MCP_COMMUNITY_CONFIG at it:

docker run \
  -v ~/.config/note-mcp-community/config.json:/run/secrets/note-mcp-community-config.json:ro \
  -e NOTE_MCP_COMMUNITY_CONFIG=/run/secrets/note-mcp-community-config.json \
  your-agent-image

Related MCP server: notion-private-api-mcp

Install / run

npx note-mcp-community

For local development:

npm install
npm run build
node dist/index.js

MCP client configuration

Recommended desktop setup after npx note-mcp-community auth:

{
  "mcpServers": {
    "note": {
      "command": "npx",
      "args": ["-y", "note-mcp-community"]
    }
  }
}

Advanced env-based setup:

{
  "mcpServers": {
    "note": {
      "command": "npx",
      "args": ["-y", "note-mcp-community"],
      "env": {
        "NOTE_COOKIE": "your note.com Cookie header"
      }
    }
  }
}

Codex CLI

For Codex, add note-mcp-community as a stdio MCP server with npx:

codex mcp add note -- npx -y note-mcp-community
codex mcp list
npx -y note-mcp-community auth --status

Recommended verification flow:

1. npx note-mcp-community auth

2. npx note-mcp-community auth --status

3. codex mcp add note -- npx -y note-mcp-community

4. Restart Codex or create a new thread

5. Run note_auth_status

If the server is listed but note_* tools are not available in the current thread, restart Codex or start a new thread so the MCP tools are loaded from the new configuration.

Authentication

note-mcp-community supports two authentication paths.

1. Local/desktop: browser login

For local desktop agents, ask the agent to call:

• note_auth_login

Or run it directly:

npx note-mcp-community auth

This opens a browser, lets you log in to note.com normally, then stores note.com cookies in:

~/.config/note-mcp-community/config.json

The CLI and MCP tool response include the actual configPath used.

If the browser executable is not installed yet, install Playwright's Chromium once on the same machine/user account, then retry:

npx playwright install chromium

When using note-mcp-community only through npx and Playwright is not otherwise installed globally/in the project, this form is often more reliable:

npx -p playwright playwright install chromium

For remote servers, containers, or CI, prefer the secret/env/config-file path below instead of browser login.

Useful CLI commands:

npx note-mcp-community auth --status
npx note-mcp-community auth --clear
npx note-mcp-community auth --headless
npx note-mcp-community auth --headed

2. Advanced/server/CI: secret, env, or config file

For remote agents, servers, containers, CI, and secret managers, provide a Cookie header via:

• NOTE_COOKIE

• NOTE_SESSION_COOKIE

• NOTE_MCP_COMMUNITY_CONFIG pointing to a config JSON file

• MCP tool note_set_cookie

Example config file:

{
  "cookie": "your note.com Cookie header",
  "updatedAt": "2026-06-21T00:00:00.000Z"
}

Cookie lookup priority:

1. NOTE_COOKIE

2. NOTE_SESSION_COOKIE

3. config file cookie

Default config path:

~/.config/note-mcp-community/config.json

Override config path:

NOTE_MCP_COMMUNITY_CONFIG=/path/to/config.json npx note-mcp-community

Tools

Authentication/setup tools:

• note_auth_status — inspect whether auth is configured and which config path is used

• note_auth_login — open a browser login flow and save cookies locally; response includes configPath

• note_set_cookie — save a Cookie header to the local config file, optionally verifying it first

• note_clear_cookie — delete the stored config-file cookie

• note_login_help — explain supported setup paths

note.com tools:

• note_auth_check — verify configured cookie-based access to note.com internal APIs

• note_list_my_notes — list notes for the authenticated account via GET /v2/note_list/contents?limit={limit}&page={page}. Defaults to LLM-friendly summary output; pass fields: "full" for the raw internal API payload.

• note_list_drafts — list drafts for the authenticated account via GET /v2/note_list/contents?limit={limit}&page={page}&status=draft&without_magazines=true. Defaults to LLM-friendly summary output; pass fields: "full" for the raw internal API payload.

• note_get_note — fetch a note by note key, e.g. n1a0b26f944f4. Defaults to compact fields (id, key, status, name, noteUrl, eyecatch, bodyPreview, bodyLength, isDraft, canUpdate); pass responseFormat: "full" for the raw payload, includeBody: true for body content, or fields: [...] to pick specific fields.

• note_get_draft — fetch authenticated draft detail by note key via GET /v3/notes/{noteKey}?draft=true&draft_reedit=false

• note_create_draft — create a draft by first calling POST /v1/text_notes with an empty-body editor payload to obtain data.id/data.key, then saving content via draft_save. By default returns an LLM-friendly summary with id/noteId, key/noteKey, editUrl, publicUrl, and nextActions; pass responseFormat: "full" for raw responses.

• note_update_draft — update a draft by numeric draftId or by noteKey (the tool resolves numeric id internally). By default returns a compact summary; pass responseFormat: "full" for raw responses.

• note_publish_draft — publicly publish a draft by note key; internally resolves the numeric id from draft detail, then calls PUT /v1/text_notes/{id} with note.com's current publish payload. By default returns status, key, noteUrl, eyecatch, and publishedAt; pass responseFormat: "full" for raw responses.

• note_upload_eyecatch — upload an eyecatch/cover image via POST /v1/image_upload/note_eyecatch. Provide numeric noteId or noteKey; noteKey is resolved internally. Provide imagePath or imageUrl; width/height default to note.com's recommended 1280x670. The tool checks the 10MB upload limit and can read back compact state with verify: true when noteKey is supplied.

• note_prepare_draft — high-level agent tool: create draft, optionally upload eyecatch, and return compact status, noteId, noteKey, noteUrl, and eyecatch result.

• note_update_draft_bundle — high-level agent tool: update an existing draft by noteKey, optionally upload eyecatch, and return compact ids/URLs.

• note_markdown_to_note_html — optional helper that converts simple Markdown headings, paragraphs, bullet lists, emphasis, and links to conservative note-compatible HTML.

• note_delete_draft — delete an unpublished draft by numeric draft/note id via DELETE /v1/text_notes/draft_delete?id={draftId}

• note_delete_note — delete a published/deletable note by note key via DELETE /v1/notes/n/{noteKey}

If authentication is missing, note tools return an auth_required error suggesting note_auth_login or note_set_cookie.

Body format for AI agents

note_create_draft and note_update_draft send body directly to note.com's internal editor API. note.com does not automatically render Markdown in this field.

If you want headings, lists, links, or emphasis to appear formatted, pass note-compatible HTML:

<h2>テスト内容</h2>
<ul>
  <li>下書き作成</li>
  <li>公開</li>
</ul>

Do not pass Markdown if visual formatting is expected:

## テスト内容

- 下書き作成
- 公開

AI agents should generate or convert content to note-compatible HTML before calling the tool. note-mcp-community intentionally stays a thin bridge to note.com's API; Markdown-to-HTML conversion belongs in the caller or a future optional helper, not in the core draft tools.

Recommended body HTML:

• <h2>, <h3> for headings

• <p> for paragraphs

• <ul><li> / <ol><li> for lists

• <strong>, <em> for emphasis

• <a href="..."> for links

Avoid:

• Full HTML documents (<html>, <head>, <body>)

• Inline scripts/styles

• Unsupported custom attributes

Troubleshooting

id is missing when saving a draft

POST /v1/text_notes/draft_save is an update/save endpoint and requires a numeric draft id in the query string. New draft creation should use the two-step editor flow:

1. POST /v1/text_notes to create an empty draft shell and read data.id / data.key.

2. POST /v1/text_notes/draft_save?id={draftId}&is_temp_saved=true to save the title and body.

If an agent reports a fallback from draft_save without an id, first check that the running MCP server is using the current package/build and not a cached or stale npx install. For existing drafts, call note_update_draft with either draftId or noteKey; do not call draft_save as a create endpoint.

API basis

The initial endpoints are based on public, unofficial note API references, including:

• https://note.com/ego_station/n/n1a0b26f944f4

Known endpoint basis:

• Base URL: https://note.com/api

• Note detail: GET /v3/notes/{noteKey}

• Draft detail: GET /v3/notes/{noteKey}?draft=true&draft_reedit=false&ts={timestamp}

• Authenticated note list: GET /v2/note_list/contents?limit=20&page=1

• Authenticated draft list: GET /v2/note_list/contents?limit=20&page=1&status=draft&without_magazines=true

• Draft shell create/id lookup: POST /v1/text_notes with { "body": "", "body_length": 0, "name": "...", "index": false, "is_lead_form": false }; response includes numeric data.id and note data.key. Mutating editor requests should include Origin: https://editor.note.com, Referer: https://editor.note.com/, X-Requested-With: XMLHttpRequest, and Content-Type: application/json.

• Draft save/update: POST /v1/text_notes/draft_save?id={draftId}&is_temp_saved=true with body, body_length, name, index, and is_lead_form

• Draft publish: PUT /v1/text_notes/{draftId} with free_body, pay_body, body_length, and status: "published"

• Eyecatch upload: POST /v1/image_upload/note_eyecatch as multipart/form-data with note_id, binary file, width, and height. The default/recommended image dimensions are 1280x670.

• Draft delete: DELETE /v1/text_notes/draft_delete?id={draftId}

• Published/deletable note delete: DELETE /v1/notes/n/{noteKey}

• Auth smoke test: GET /v3/notice_counts

note_list_my_notes and note_list_drafts intentionally expose the authenticated note list endpoints above. The response shape is determined by note.com's internal API and typically returns items under data.notes; summary mode is the default to reduce agent token usage, and fields: "full" is available when debugging endpoint behavior. Summary mode does not invent public URLs for drafts unless note.com returns an explicit URL/path.

Release

Releases are handled by GitHub Actions + semantic-release.

• Push or merge Conventional Commits into main.

• GitHub Actions runs CI.

• The release workflow creates GitHub tags/releases and publishes to npm.

npm publishing uses npm Trusted Publishing with GitHub Actions OIDC. Configure new-village/note-mcp-community and .github/workflows/release.yml as a trusted publisher on npmjs.com. No NPM_TOKEN repository secret is required.

Development

npm run typecheck
npm test
npm run build
npm run lint

License

MIT