Connect NoteLLM To AI Clients

What this is

NoteLLM provides a hosted MCP server plus an official plugin that lets AI agents retrieve your saved raw note transcripts through skills.

• Official plugin: hx23840/notellm-plugin
• MCP Server URL: https://notellm.app/api/mcp
• Transport: Streamable HTTP
• Auth: OAuth 2.1 with PKCE
• Minimum scope: asr:read

The recommended setup is to install the plugin. It adds the NoteLLM skills and configures the hosted MCP server for supported local clients.

What Gets Installed

The plugin provides two skills:

The MCP server provides the underlying tools:

These MCP tools are called by the agent after the plugin and OAuth are configured. They are not skills and do not appear in the skills list.

Support Matrix

Codex

Install the official plugin:

npx notellm-plugin install --client codex

The installer adds the NoteLLM skills and registers the MCP server.

Codex starts the NoteLLM OAuth flow when the MCP server is added. Open the authorization URL, sign in to NoteLLM, and approve the asr:read scope.

Verify the MCP server:

codex mcp list

You should see:

notellm  https://notellm.app/api/mcp

Then start Codex and ask:

Show my recent NoteLLM notes.

You can also select a skill directly. In Codex, these may appear with the package prefix:

$notellm:notellm-recent-notes
$notellm:notellm-search-notes

Claude Code

Run the installer from the project where you use Claude Code:

npx notellm-plugin install --client claude-code

Claude Code MCP config is project-scoped. After installation, the output should include something like:

Added HTTP MCP server notellm with URL: https://notellm.app/api/mcp to project config
File modified: .mcp.json

This is expected. Claude Code does not start OAuth during mcp add.

Start Claude Code from the same project:

claude

Choose notellm-recent-notes from the skills list, or ask:

Show my recent NoteLLM notes.

Claude Code starts OAuth from the client session when the NoteLLM MCP tool is first used.

Useful verification command:

claude mcp list

Install For Both Local Clients

To install NoteLLM for both Codex and Claude Code:

npx notellm-plugin install --client all

The interactive installer is also available:

npx notellm-plugin install

Update and uninstall use the same client selector:

npx notellm-plugin update --client codex
npx notellm-plugin uninstall --client codex

You can replace codex with claude-code or all.

Claude

Use this for Claude on the web or any Claude client that supports custom connectors.

1. Open Connectors in Claude settings
2. Choose Add custom connector
3. Enter https://notellm.app/api/mcp
4. Save it and click Connect
5. Complete the browser sign-in flow on notellm.app and approve asr:read

After the connector is authenticated, ask Claude:

Use the NoteLLM MCP tools to list my recent raw notes with limit 10. Show them briefly first. If I mention a topic, search_notes for it. If I choose one note, open it with get_note.

How To Use It

Use natural requests:

Show my recent NoteLLM notes.

Find my NoteLLM notes about the mobile app launch.

What did I previously say in NoteLLM about pricing?

When notellm-recent-notes is selected, the agent should immediately retrieve recent notes.

When notellm-search-notes is selected, the agent should search NoteLLM using the current conversation. If there is no usable topic, it asks what to search.

Recommended Usage Pattern

Use the tools in this order:

1. Call list_recent_notes with a small limit, such as 10
2. Show the recent notes briefly
3. If the user mentions a topic or earlier idea, call search_notes
4. Let the user choose one or more note IDs
5. Call get_note or batch_get_notes only for the selected items

Do not fetch large batches of full raw transcripts by default.

Manual Configuration Details

Most users should use the plugin installer instead of manual configuration. If your client supports MCP discovery, the server URL is usually enough.

• MCP Server URL: https://notellm.app/api/mcp
• OAuth Protected Resource Metadata: https://notellm.app/.well-known/oauth-protected-resource
• OAuth Authorization Server Metadata: https://notellm.app/.well-known/oauth-authorization-server
• OAuth Scope: asr:read

FAQ

Why use the plugin instead of only adding MCP?

The MCP server gives the agent access to your raw NoteLLM transcripts. The skills tell the agent when to use that access and how to keep retrieval narrow.

Use the plugin when you want the behavior to be consistent instead of relying on each prompt to explain when and how to call NoteLLM.

Why can't I just paste a prompt into the agent?

Because most MCP clients require two setup steps before tool calls work:

• the MCP server must be registered in the client
• OAuth authentication must be completed first

Only after both steps succeed can the client actually call NoteLLM MCP tools.

Why does the model treat the tool name as plain text?

If the notellm MCP server is not connected and loaded successfully, the model only sees list_recent_notes or search_notes as text, not as available tools.

How do I know the connection is working?

Use the client's own MCP status surface:

• Codex: codex mcp list
• Claude Code: claude mcp list or /mcp
• Claude: connector state in settings