Skip to main content
Glama
Mhdd-24

notepadpp-mcp

by Mhdd-24

@mhdd_24/notepadpp-mcp

MCP server for Notepad++ on Windows. Use it from Cursor, Claude Desktop, VS Code Copilot, or any MCP-compatible client to open files, check editor status, and save/load session snapshots.

Full documentation: docs/WIKI.md


How it works (30 seconds)

You (chat) → MCP client → notepadpp-mcp → notepad++.exe / session.xml
  1. Status — resolves NOTEPADPP_EXE, checks if the process is running

  2. Open / new — launches Notepad++ with file paths or a fresh buffer

  3. Sessions — reads live session.xml; save/load named snapshots via -openSession


Related MCP server: technical-notes-mcp

Prerequisites

Requirement

Notes

Node.js 18+

Required for MCP server

Notepad++ 8+

Default: C:\Program Files\Notepad++\notepad++.exe

Windows

CLI + session.xml (no Python)


Install

npm install -g @mhdd_24/notepadpp-mcp

Option B — npx (no global install)

npx @mhdd_24/notepadpp-mcp

Option C — clone and build (contributors)

git clone https://github.com/Mhdd-24/NotePadpp-MCP.git
cd NotePadpp-MCP
npm install
npm run build
node dist/index.js

Configure your MCP client

Cursor

Edit Cursor Settings → MCP or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "notepadpp": {
      "command": "npx",
      "args": ["-y", "@mhdd_24/notepadpp-mcp"],
      "env": {
        "NOTEPADPP_EXE": "C:/Program Files/Notepad++/notepad++.exe",
        "NOTEPADPP_WORKDIR": "C:/Users/You/Documents/NotepadPP-Notes"
      }
    }
  }
}

After global install, you can use:

"command": "notepadpp-mcp"

Local development:

"command": "node",
"args": ["C:/path/to/notepadpp-mcp/dist/index.js"]

Restart Cursor (or toggle the MCP server off/on) after saving.


Environment variables

Variable

Required

Default

Purpose

NOTEPADPP_EXE

No

Program Files path

Path to notepad++.exe

NOTEPADPP_WORKDIR

No

%USERPROFILE%\Documents\NotepadPP-Notes

Base for relative paths

NOTEPADPP_SESSION_XML

No

%APPDATA%\Notepad++\session.xml

Live session file

NOTEPADPP_SESSION_STORAGE_DIR

No

%APPDATA%\Notepad++\notepadpp-mcp-sessions

Named snapshots

Never commit machine-specific paths that identify private orgs. Put local overrides only in MCP env or a gitignored .env.


Tools

Tool

Purpose

npp_status

Exe path, process running, session/workdir

npp_open

Open file(s) in Notepad++

npp_new

New empty buffer or create+open a file

npp_list_session

List paths from live session.xml

npp_save_session

Snapshot live session under a name

npp_load_session

Load named session via -openSession

npp_run

Escape hatch with custom CLI args


What happens after npm install?

  1. Package files land in node_modules/@mhdd_24/notepadpp-mcp/ (or global prefix if -g).

  2. prepack / publish includes compiled dist/ — no local build needed for end users.

  3. The notepadpp-mcp bin points to dist/index.js.

  4. Your MCP client runs that entry over stdio.

  5. Tools are registered; the server waits for CallTool requests from the AI.


After publishing to npm (maintainers)

  1. Bump version in package.json and src/config/notepadpp.config.ts (NPP.SERVER.VERSION).

  2. Build and test: npm run build then test with local mcp.json.

  3. Publish: npm publish --access public (logged in as package owner).

  4. Users update by restarting MCP — npx picks up the new version automatically.

Current package version: 1.0.1.

See WIKI — Publishing for the checklist.


Troubleshooting

Problem

Fix

Exe not found

Set NOTEPADPP_EXE

Empty session list

Open saved files in Notepad++, then retry

Session load opens new window

Check Notepad++ multi-instance preferences


License

ISC

Available Tools

7 tools
npp_list_sessionA

List file paths from the live Notepad++ session.xml (open/recent buffers).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that the tool reads from the live session.xml and outputs file paths, implying a read-only operation. However, it could be more explicit about side effects (none) and performance, but for a simple list it is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence that conveys all necessary information without superfluous words. It is front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the description sufficiently explains what the tool does: listing file paths of open/recent buffers from the live session.xml. It is complete for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema coverage is 100%. The description adds no parameter info because none are needed. According to guidelines, 0 parameters baseline is 4, and this meets that standard.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'list' and the resource 'file paths from the live Notepad++ session.xml', specifying it covers open/recent buffers. It effectively distinguishes from sibling tools like npp_load_session or npp_open by focusing on listing without modification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for viewing current open/recent buffers but lacks explicit guidance on when to use this tool vs alternatives such as npp_load_session for loading saved sessions or npp_status for other status info. The usage context is mostly implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

npp_load_sessionC

Load a named session snapshot via notepad++.exe -openSession.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesSession name (without .xml) previously saved with npp_save_session.

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must carry full burden. It mentions the command line but does not disclose potential side effects (e.g., overwriting current session), permissions, or state changes. Minimal behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one short sentence, concise but unstructured. It lacks front-loading of key information and does not prioritize critical details. Adequate but not optimized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has a single parameter, no output schema, and no annotations, the description should cover loading behavior, state impact, and error conditions. It only provides the command invocation, leaving significant gaps for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the parameter description is adequate. The tool description repeats the schema's 'name' detail but adds the command line context, offering marginal added value. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (Load) and resource (named session snapshot), and references the underlying command. However, it does not distinguish from sibling tools like npp_list_session or npp_save_session, missing the opportunity to clarify scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or context. Given siblings like npp_list_session and npp_save_session, explicit usage advice would significantly improve selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

npp_newB

Launch Notepad++ with a new empty document. Optionally create and open a new file under NOTEPADPP_WORKDIR.

ParametersJSON Schema
NameRequiredDescriptionDefault
filenameNoOptional new file name (relative to NOTEPADPP_WORKDIR or absolute). Creates an empty file if missing.
multiInstanceNoIf true, pass -multiInst.

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It mentions launching Notepad++ and optionally creating a file but lacks details on blocking behavior, prerequisites (e.g., Notepad++ installation), environment variable NOTEPADPP_WORKDIR, or effects of the multiInstance parameter. Important behavioral traits are missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action, and contains no redundant information. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two optional parameters and no output schema, the description covers the main purpose but omits important context: prerequisites (e.g., Notepad++ must be installed), explanation of NOTEPADPP_WORKDIR, and when to use multiInstance. It is adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes both parameters with 100% coverage, but the description adds context for 'filename' by stating it is relative to NOTEPADPP_WORKDIR or absolute, which enriches meaning. The 'multiInstance' parameter is not elaborated in the description, but the schema covers it. Overall, the description adds meaningful value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool launches Notepad++ with a new empty document, distinguishing it from siblings like npp_open which likely open existing files. However, it does not explicitly contrast with sibling tools, so it misses the top score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like npp_open or npp_run. It simply states what it does without any usage context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

npp_openA

Open one or more files in Notepad++. Paths may be absolute or relative to NOTEPADPP_WORKDIR.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathsYesFile path(s) to open.
multiInstanceNoIf true, pass -multiInst so a separate Notepad++ instance is used.

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It adds path relativity detail but omits other behavioral traits like error handling, return values, or whether it blocks. For a mutation tool with no annotations, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundancy, direct and efficient. Every word contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity (2 params, no output schema), the description covers core purpose and path format but omits return value and potential side effects. Adequate but could be more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining path relativity for the 'paths' parameter but does not enhance 'multiInstance' (already clear in schema). Overall, marginal value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Open') and the resource ('files in Notepad++'). It also specifies path handling (absolute or relative to NOTEPADPP_WORKDIR), distinguishing it from siblings like npp_new (create) or npp_load_session (load session).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for opening files but provides no explicit guidance on when to use this versus alternatives (e.g., npp_load_session for session files). No exclusion criteria are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

npp_runB

Escape hatch: run notepad++.exe with custom CLI arguments.

ParametersJSON Schema
NameRequiredDescriptionDefault
argsNoArguments passed to notepad++.exe (e.g. ["-nosession", "C:/path/file.txt"]).

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description merely states it runs the executable without detailing side effects, process behavior, output handling, or safety implications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words, though it could benefit from slightly more structure (e.g., separating purpose from behavior).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's potential impact (running arbitrary CLI arguments), the description lacks necessary context about prerequisites, return values, and process behavior, making it incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the description adds the context 'escape hatch' but does not further clarify parameter usage beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs notepad++.exe with custom CLI arguments, distinguishing it from sibling tools that manage sessions or open files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Escape hatch' implies it is an advanced fallback, but there is no explicit guidance on when to use it versus the sibling tools, nor any when-not or alternative hints.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

npp_save_sessionB

Copy the live session.xml into a named snapshot under the session storage folder.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesSession name (without .xml). Letters, digits, dash, underscore.

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only describes the copying action without disclosing traits like overwrite behavior, permissions needed, or effect on the live session.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence that is clear and efficient. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and no output schema. The description covers the basic action but lacks context on side effects, return values, or error conditions. Adequate but minimal.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds no additional meaning beyond the schema's parameter description. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Copy') and the resource ('live session.xml' into a named snapshot), and the verb-resource combination distinguishes it from sibling tools like npp_list_session and npp_load_session.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as npp_new or npp_save. The description does not mention prerequisites or context for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

npp_statusA

Check Notepad++ availability: exe path, whether the process is running, and resolved session/workdir paths.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses what information is checked, which is sufficient for a read-only status tool. However, it does not mention potential performance or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no wasted words. Front-loaded with the purpose and efficiently lists the key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter status check tool, the description fully explains what it does and what information it provides. No output schema exists, but the description covers the expected return details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist (0 params, schema coverage 100%), so baseline is 4. The description adds meaning by listing the specific status items, which is valuable beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it checks Notepad++ availability and lists specific items (exe path, process running, session/workdir paths). The verb 'Check' combined with the resource and details distinguishes it from sibling tools like npp_run or npp_list_session.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use or not use this tool versus alternatives. Usage is implied as a status check, but no when-not or sibling differentiation beyond the purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 7 tool updatesv1.0.1
    • First observednpp_list_session
    • First observednpp_load_session
    • First observednpp_new
    • First observednpp_open
    • First observednpp_run
    • First observednpp_save_session
    • First observednpp_status

TDQS

A3.6/5.0
Disambiguation5/5

Each tool targets a distinct operation: listing sessions, loading sessions, creating new documents, opening files, running custom commands, saving sessions, and checking status. There is no functional overlap.

Naming Consistency4/5

All tools use the 'npp_' prefix followed by a descriptive verb_noun pattern (e.g., list_session, load_session, save_session). 'npp_new' is slightly inconsistent as 'new' is an adjective, but still follows the pattern.

Tool Count5/5

Seven tools cover the essential operations for Notepad++ session and file management without being excessive or insufficient for the server's purpose.

Completeness4/5

The set covers session management (list, load, save), file operations (new, open), and system integration (run, status). Minor gaps like closing files or editing are absent but not critical for the core use case.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Mhdd-24/NotePadpp-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server