📝 MCP Personal Notes Server

A beginner-friendly Model Context Protocol (MCP) server that lets AI applications manage personal notes through structured tools.

🚀 Live Demo

Server: https://mcp-personal-notes-server.onrender.com/

MCP Endpoint: https://mcp-personal-notes-server.onrender.com/mcp

The root URL intentionally returns a small JSON status response. The /mcp endpoint is the actual MCP protocol endpoint and is meant to be used by an MCP client or MCP Inspector.

Related MCP server: Beeper MCP Note Server

📸 Project Screenshots

🌐 Live Server

The deployed server returns a health/status response from the root URL.

🔌 MCP Inspector — Connected

The deployed Streamable HTTP MCP endpoint is connected successfully through MCP Inspector.

🧰 Available MCP Tools

The server exposes five note-management tools: save_note, list_notes, get_note, search_notes, and delete_note.

📝 Save Note

A note can be created directly through the save_note MCP tool.

🗄️ PostgreSQL Database

Notes created through the MCP server are persisted in PostgreSQL.

☁️ Render Deployment

The production logs show PostgreSQL initialization, the MCP server starting, and the deployed service becoming available.

💡 What is this project?

The MCP Personal Notes Server is a simple project for learning how the Model Context Protocol works.

Instead of building a traditional notes REST API, this project exposes note-management capabilities as MCP tools.

An MCP-compatible AI client can use tools such as:

• save_note

• list_notes

• get_note

• search_notes

• delete_note

The project demonstrates the complete flow:

AI / MCP Client
       │
       │ MCP
       ▼
MCP Personal Notes Server
       │
       │ SQL
       ▼
PostgreSQL

✨ Features

• 📝 Create personal notes

• 📋 List saved notes

• 🔎 Search notes by title, content, or category

• 📖 Retrieve a note by ID

• 🗑️ Delete notes

• 🗄️ PostgreSQL persistence

• 🌐 Deployed MCP endpoint

• 🔐 Environment-variable based database configuration

• 🧪 Testable with MCP Inspector

• 📦 Beginner-friendly Node.js implementation

🛠️ Tech Stack

Technology Purpose

JavaScript Application language Node.js Runtime Express.js HTTP server MCP SDK Model Context Protocol implementation PostgreSQL Persistent database Neon Hosted PostgreSQL Render Application deployment MCP Inspector MCP testing

🧰 MCP Tools

1. save_note

Creates a new note.

Input:

{
  "title": "Learn MCP",
  "content": "Understand how MCP tools work.",
  "category": "Learning"
}

2. list_notes

Returns all saved notes.

Input:

{}

3. get_note

Retrieves one note using its UUID.

Input:

{
  "id": "NOTE_UUID"
}

4. search_notes

Searches note title, content, and category.

Input:

{
  "query": "MCP"
}

5. delete_note

Deletes a note using its UUID.

Input:

{
  "id": "NOTE_UUID"
}

🏗️ Architecture

                         ┌─────────────────────┐
                         │    AI / MCP Client   │
                         └──────────┬──────────┘
                                    │
                                    │ MCP / HTTP
                                    ▼
                    ┌─────────────────────────────┐
                    │   MCP Personal Notes Server │
                    │                             │
                    │  save_note                  │
                    │  list_notes                 │
                    │  get_note                   │
                    │  search_notes               │
                    │  delete_note                │
                    └──────────────┬──────────────┘
                                   │
                                   │ SQL
                                   ▼
                    ┌─────────────────────────────┐
                    │         PostgreSQL           │
                    │                             │
                    │           notes             │
                    └─────────────────────────────┘

Deployment Architecture

GitHub
   │
   │ Deploy from repository
   ▼
Render
   │
   │ DATABASE_URL
   ▼
Neon PostgreSQL

📁 Project Structure

mcp-personal-notes-server/
│
├── src/
│   ├── server.js
│   ├── database.js
│   ├── database-init.js
│   ├── storage.js
│   │
│   └── tools/
│       └── notes.js
│
├── .env
├── .gitignore
├── package.json
├── package-lock.json
└── README.md

Important files

src/server.js

Creates the Express application, MCP server, HTTP transport, health endpoint, and /mcp endpoint.

src/database.js

Creates the PostgreSQL connection pool.

src/database-init.js

Creates the notes table when the server starts.

src/storage.js

Contains database operations for creating, reading, searching, and deleting notes.

src/tools/notes.js

Registers the five MCP tools.

⚙️ Run Locally

1. Clone the repository

git clone https://github.com/SRCarlo/mcp-personal-notes-server.git
cd mcp-personal-notes-server

2. Install dependencies

npm install

3. Create .env

Create a .env file in the project root:

PORT=3000
DATABASE_URL=YOUR_POSTGRESQL_CONNECTION_STRING

Never commit .env to GitHub.

4. Start development server

npm run dev

Expected output:

PostgreSQL connected successfully.
Database initialized successfully.
MCP Personal Notes Server running on port 3000
MCP endpoint: http://localhost:3000/mcp

5. Check health

Open:

http://localhost:3000/health

Expected:

{
  "status": "healthy"
}

🧪 Test with MCP Inspector

Start MCP Inspector:

npx @modelcontextprotocol/inspector

For local testing use:

http://localhost:3000/mcp

For the deployed server use:

https://mcp-personal-notes-server.onrender.com/mcp

Select:

Streamable HTTP

After connecting, open the Tools tab.

You should see:

save_note
list_notes
get_note
search_notes
delete_note

☁️ Deployment

This project is deployed using:

• Render for the Node.js MCP server

• Neon for PostgreSQL

Render configuration

Build Command

npm install

Start Command

npm start

Environment variables

NODE_ENV=production
DATABASE_URL=YOUR_NEON_CONNECTION_STRING

The application uses Render's PORT environment variable automatically:

const PORT = process.env.PORT || 3000;

🔒 Security

This project follows a few basic security practices:

• Database credentials are stored in environment variables.

• .env is excluded from Git.

• SQL queries use PostgreSQL parameterized queries.

• The application does not expose the database connection string.

• Production configuration is supplied through Render environment variables.

Never publish your real DATABASE_URL in source code or GitHub.

🧠 What I Learned

This project was built to understand:

• What MCP is

• How MCP servers expose tools

• How an AI client can discover and call tools

• Streamable HTTP transport

• Node.js server development

• PostgreSQL integration

• Environment variables

• MCP Inspector testing

• Git and GitHub workflow

• Cloud deployment

• Connecting a deployed MCP server to an MCP client

🗺️ Future Improvements

Possible next versions:

• Add update_note

• Add get_recent_notes

• Add tags

• Add pagination

• Add authentication

• Add note ownership/user accounts

• Add full-text PostgreSQL search

• Add automated tests

• Add CI/CD with GitHub Actions

• Connect to an AI client for natural-language note management

🎯 Example AI Workflow

Once connected to an MCP-compatible AI client, the goal is to support natural-language requests such as:

Save a note titled "Learn Spring Boot" with the content "Study Spring Security and REST APIs" under the category "Learning".

The AI can discover the available MCP tools and call:

save_note()

The resulting note is stored in PostgreSQL.

Another request could be:

Find my notes about MCP.

The AI can use:

search_notes()

This is the main idea behind the project:

Natural Language
       ↓
AI
       ↓
MCP Tool
       ↓
Your Server
       ↓
PostgreSQL

📌 Project Status

Status: 🟢 Deployed and working

MCP Transport: Streamable HTTP

Database: PostgreSQL

Deployment: Render + Neon

Testing: MCP Inspector

👨‍💻 Author

Shubham Raut — SRCarlo

Full Stack Java Developer | AI • Gen AI • IoT • Cloud

I build full-stack applications, AI-powered projects, and developer-focused tools while continuously exploring new technologies.

🔗 GitHub: @SRCarlo | 🌐 Portfolio: Shubham Raut | 💼 LinkedIn: Shubham Raut

📄 License

This project is available under the MIT License.

⭐ Support

If you found this project useful for learning MCP, AI tools, or backend development, consider giving the repository a ⭐.