@randomfact/memnote-mcp-server
v0.4.0
Published
MCP server for MemNote.
Readme
@randomfact/memnote-mcp-server
An MCP server for MemNote. Connect any MCP-compatible AI assistant — Claude, ChatGPT, Claude Desktop, Claude Code, Cursor, Continue, and others — to your MemNote account so it can create, search, and manage your notes for you.
Easiest: use the hosted server (no install)
MemNote runs a hosted MCP server that any remote-MCP-capable client can connect to:
https://mcp.memnote.randomfact.com- Claude (claude.ai): Settings → Connectors → Add custom connector → paste the URL above → sign in to MemNote when prompted.
- ChatGPT: Settings → Connectors (requires Developer Mode) → Create → paste the URL above → sign in to MemNote when prompted.
- Claude Code:
claude mcp add --transport http memnote https://mcp.memnote.randomfact.com
Authentication is handled by your browser via MemNote's standard sign-in — no tokens to copy.
The rest of this README covers the local stdio server (npm package), which is useful for clients without remote MCP support, offline/self-hosted setups, and development.
Quick start
npx -y @randomfact/memnote-mcp-serverOn first run, your browser opens to MemNote's sign-in page. After you approve, the server caches an OAuth token locally and reuses it on subsequent runs.
By default the server connects to https://api.memnote.randomfact.com and registers itself as an OAuth client the first time it runs — there is nothing to set up. Override with --base-url / --client-id if you're pointing at a self-hosted instance.
Use with Claude Desktop
Edit your Claude Desktop config:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Add a memnote entry under mcpServers:
{
"mcpServers": {
"memnote": {
"command": "npx",
"args": ["-y", "@randomfact/memnote-mcp-server"]
}
}
}Restart Claude Desktop. The first time you use a MemNote tool, a browser tab opens for sign-in.
Use with Claude Code
Register the server with the Claude Code CLI:
claude mcp add memnote -- npx -y @randomfact/memnote-mcp-serverUse with other MCP clients
The server defaults to MCP's stdio transport, so anything that speaks stdio works unchanged. For Cursor, Continue, and similar clients, add an mcpServers entry with the same command + args shape shown above.
Authentication
On first use the server runs a standard OAuth authorization-code flow with PKCE:
It registers itself with MemNote's authorization server (RFC 7591 dynamic client registration) and caches the client id. Registration is idempotent, so every install of this package shares one client identity rather than creating a new one per machine or per run.
It opens your default browser to MemNote's sign-in page.
After you approve, MemNote redirects to a short-lived loopback server on the first free port in
127.0.0.1:8765-8774.The resulting tokens — and the cached client id — are written to a per-user file with mode
0600:| OS | Token path | | ------- | --------------------------------------------------- | | Linux |
~/.config/memnote-mcp/tokens.json| | macOS |~/Library/Application Support/memnote-mcp/tokens.json| | Windows |%APPDATA%\memnote-mcp\tokens.json|
Subsequent runs reuse the cached token and refresh it silently when it expires. To sign out, delete the token file.
Headless / SSH systems
If the loopback redirect can't reach a browser on the machine running the server, add --manual-code:
npx -y @randomfact/memnote-mcp-server --manual-codeThe server prints an authorization URL. Open it in any browser and approve. Your browser then tries to load http://127.0.0.1:8765/callback?code=… and fails — that is expected. Copy the code query parameter out of the address bar and paste it back into the terminal.
CLI flags
Most users don't need any of these — the defaults work. They're listed here for the cases that come up.
| Flag | Description |
| -------------------------- | ---------------------------------------------------------------------------------------------------- |
| --manual-code | Paste the authorization code instead of using a loopback redirect (headless/SSH). |
| --token-store <file> | Override the token cache location. |
| --transport stdio\|http | Transport to expose. Default stdio. http serves MCP Streamable HTTP at /mcp (local use). |
| --port <n> | Port for the http transport. Default 3100. |
| --host <addr> | Bind address for the http transport. Default 127.0.0.1. |
| --loopback-port <n> | Pin the loopback redirect to one port instead of the default 8765-8774 range. |
| --client-id <id> | Skip dynamic registration and use a pre-existing OAuth client (self-hosted / development). |
Troubleshooting
Browser doesn't open / loopback hangs. Use --manual-code to copy-paste the authorization code instead.
"Token expired" or 401 errors. Delete the token file (see paths above) and re-run — the server will start a fresh OAuth flow.
invalid_client during sign-in. The cached client id no longer resolves on the server you're pointing at. Delete the token file to force a fresh registration.
Tools missing or out of date. The catalog is built from ${baseUrl}/docs/json at startup (https://api.memnote.randomfact.com/docs/json by default). Restart your MCP client to refetch.
Verbose logs. Set MEMNOTE_MCP_LOG_LEVEL=debug. Logs go to stderr; stdout is reserved for the MCP protocol.
