notes-mcp-server

balgaly/notes-mcp-server

3.1

If you are the rightful owner of notes-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A simple Model Context Protocol (MCP) server for note-taking functionality integrated with Claude Desktop.

Tools
5
Resources
0
Prompts
0

Notes MCP Server

A simple Model Context Protocol (MCP) server that provides note-taking functionality for Claude Desktop. This server allows Claude to create, read, update, and delete notes stored as JSON files.

🎯 Purpose

This project was created as a hands-on learning exercise for understanding MCP (Model Context Protocol). It demonstrates:

  • How to build an MCP server from scratch
  • TypeScript and Node.js development
  • File system operations for data persistence
  • Data validation using Zod schemas
  • Integration with Claude Desktop

✨ Features

  • Create Notes: Add new notes with titles and content
  • Read Notes: Retrieve and display existing notes
  • Update Notes: Modify the content of existing notes
  • List Notes: See all available notes
  • Delete Notes: Remove notes permanently
  • Persistent Storage: Notes are saved as JSON files in the data/ directory
  • Data Validation: All note data is validated using Zod schemas
  • Error Handling: Graceful handling of file system and validation errors

🛠️ Technologies Used

  • TypeScript: For type-safe development
  • Node.js: Runtime environment
  • Model Context Protocol SDK: For MCP server functionality
  • Zod: For data validation and type safety
  • File System: JSON files for simple persistence

📁 Project Structure

notes-mcp-server/
├── src/
│   └── index.ts          # Main MCP server implementation
├── data/                 # Directory where notes are stored as JSON files
├── build/                # Compiled JavaScript output
├── .vscode/
│   └── mcp.json          # MCP server configuration for VS Code
│   └── tasks.json        # VS Code build tasks
├── .github/
│   └── copilot-instructions.md
├── package.json          # Node.js project configuration
├── tsconfig.json         # TypeScript configuration
├── .gitignore           # Git ignore file
└── README.md            # This file

🚀 Getting Started

Prerequisites

  • Node.js 16 or higher
  • Claude Desktop (latest version)
  • VS Code (optional, for development)

Installation

  1. Clone this repository:

    git clone <repository-url>
cd notes-mcp-server

  2. Install dependencies:

    npm install

  3. Build the project:

    npm run build

  4. Test the server locally (optional):

    npm run dev

Configuration for Claude Desktop

  1. Find your Claude Desktop configuration file:

    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  2. Add your server configuration:

    {
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/absolute/path/to/notes-mcp-server/build/index.js"]
    }
  }
}

    Important: Replace /absolute/path/to/notes-mcp-server with the actual absolute path to your project directory.

    Examples:

    • Windows: "args": ["C:\\Users\\YourName\\projects\\notes-mcp-server\\build\\index.js"]
    • macOS/Linux: "args": ["/home/username/projects/notes-mcp-server/build/index.js"]

  3. Restart Claude Desktop

📖 Available Tools

Once connected to Claude Desktop, these tools will be available:

create_note

  • Description: Create a new note with a title and content
  • Parameters:
    • title (string, required): The title of the note
    • content (string): The content/body of the note

read_note

  • Description: Read the content of an existing note by title
  • Parameters:
    • title (string, required): The title of the note to read

update_note

  • Description: Update the content of an existing note
  • Parameters:
    • title (string, required): The title of the note to update
    • content (string): The new content for the note

list_notes

  • Description: Get a list of all available notes
  • Parameters: None

delete_note

  • Description: Delete an existing note
  • Parameters:
    • title (string, required): The title of the note to delete

💡 Usage Examples

Once connected to Claude Desktop, you can use natural language:

  • "Create a note titled 'Shopping List' with the content 'Milk, Eggs, Bread'"
  • "Show me my Shopping List note"
  • "Update my Shopping List to add 'Butter, Cheese'"
  • "What notes do I have?"
  • "Delete my old Shopping List note"

🗂️ Data Storage

Notes are stored as individual JSON files in the data/ directory with this structure:

{
  "title": "Shopping List",
  "content": "Milk, Eggs, Bread",
  "created": "2025-01-20T10:30:00.000Z",
  "updated": "2025-01-20T10:30:00.000Z"
}

Filenames are generated from note titles by:

  • Converting to lowercase
  • Replacing spaces with hyphens
  • Removing special characters
  • Adding .json extension

Example: "My Shopping List!" → my-shopping-list.json

🔧 Development

Available Scripts

  • npm run build: Compile TypeScript to JavaScript
  • npm run start: Build and run the server
  • npm run dev: Quick development build and run

Project Configuration

  • TypeScript: Configured for ES2022 with Node16 modules
  • Output: Compiled to build/ directory
  • Type Checking: Strict mode enabled for better error catching
  • Modules: ES modules with proper Node.js compatibility

🐛 Troubleshooting

Server not appearing in Claude Desktop

  1. Check that the path in claude_desktop_config.json is absolute and correct
  2. Verify the server builds without errors (npm run build)
  3. Restart Claude Desktop completely
  4. Check Claude Desktop logs for errors

Tools not working

  1. Ensure the data/ directory is writable
  2. Check for TypeScript compilation errors
  3. Verify all dependencies are installed

Common Issues

  • Path problems: Always use absolute paths in Claude Desktop configuration
  • Permission issues: Ensure the data/ directory has write permissions
  • TypeScript errors: Run npm run build to check for compilation issues

📄 License

This project is licensed under the MIT License - see the file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

🎓 Learning Notes

This project demonstrates several important MCP concepts:

  1. MCP Server Structure: How to set up a basic MCP server with tools
  2. Data Validation: Using Zod for input validation and type safety
  3. File Operations: Persistent storage using the Node.js file system
  4. Error Handling: Graceful error handling and user feedback
  5. TypeScript Integration: Type-safe development with modern JavaScript features

📚 Resources

🤝 Contributing

This is a learning project, but feel free to:

  • Suggest improvements
  • Report bugs
  • Add features
  • Share your own MCP server experiments

Happy coding and learning! 🚀