devonfox/notes-mcp

Markdown Notes MCP Server

An MCP (Model Context Protocol) server that creates markdown files and sends them to Discord, with support for local file saving and task management.

Features

• Send Markdown Notes: Create markdown files and send them to Discord as file attachments
• Task Management: Add tasks to a weekly todo list (local file or Discord)
• Local File Saving: Optionally save files locally in addition to Discord
• MCP Protocol: Full MCP protocol support via HTTP
• Docker Support: Easy deployment with Docker

Requirements

• Node.js 18+ (for native FormData and Blob support)
• Docker (optional, for containerized deployment)

Setup

1. Install Dependencies

npm install

2. Create a Discord Webhook

1. Go to your Discord server
2. Navigate to the channel where you want to receive notes
3. Click on the channel settings (gear icon)
4. Go to "Integrations" → "Webhooks"
5. Click "New Webhook" or "Create Webhook"
6. Give it a name (e.g., "AI Notes")
7. Copy the webhook URL

3. Configure Environment Variables

Create a .env file in the project root (you can copy from .env.example):

cp .env.example .env

Then edit .env and configure your settings:

# Required: Discord webhook URL
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your_webhook_id/your_webhook_token

# Optional: Local file path to save markdown files
# If set, files will be saved to this directory in addition to being sent to Discord
LOCAL_FILE_PATH=/Users/yourname/Documents/notes

# Optional: Path to tasks.md file for weekly todo list
# If set, tasks will be appended to this file when running locally
# If not set, tasks will be sent to Discord with a timestamped filename
TASKS_FILE_PATH=/Users/yourname/Documents/tasks.md

Or export them in your shell:

export DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your_webhook_id/your_webhook_token
export LOCAL_FILE_PATH=/Users/yourname/Documents/notes
export TASKS_FILE_PATH=/Users/yourname/Documents/tasks.md

4. Build the Project

npm run build

Usage

Running the MCP Server

The server runs on HTTP (default port 3000) and exposes MCP protocol endpoints.

npm start

For development:

npm run dev

The server will start on http://localhost:3000 (or the port specified by the PORT environment variable).

Connecting MCP Clients

Connect to the server using the MCP endpoint:

• MCP Inspector: npx @modelcontextprotocol/inspector and connect to http://localhost:3000/mcp
• Cursor: Add MCP server with URL http://localhost:3000/mcp
• ChatGPT: Turn on Development mode, and Create new connector with URL http://localhost:3000/mcp
• Claude Desktop: Configure in settings with URL http://localhost:3000/mcp
• VS Code: Add MCP server configuration

API Endpoints

GET /

API information endpoint.

GET /health

Health check endpoint.

Response:

{
  "status": "ok"
}

POST /mcp

MCP protocol endpoint. This is the main endpoint for MCP clients.

MCP Tools

The server exposes two tools:

1. send_markdown_to_discord

Creates a markdown note/document and sends it to Discord as a file attachment.

When to use: General notes, documents, summaries, or any content that should be saved as a markdown file.

Parameters:

• prompt (required): The content to convert into a markdown note
• title (optional): Title for the markdown note
• webhookUrl (optional): Discord webhook URL. If not provided, uses DISCORD_WEBHOOK_URL from environment

Behavior:

• Creates a markdown file with the content
• Sends to Discord as a file attachment
• If LOCAL_FILE_PATH is set, also saves the file locally

Example usage in MCP client:

"Create a markdown note about today's meeting: We discussed the new feature..."
"Save this summary as a markdown file: [content]"

2. add_tasks

Adds tasks or todo items to a weekly todo list.

When to use: When you want to add tasks, todos, action items, or checklist items.

Parameters:

• items (required): Array of task items. Items starting with spaces or dashes will be treated as subtasks and indented.

Behavior:

• If TASKS_FILE_PATH is set (local mode):

  • Reads existing tasks.md file
  • Appends new tasks to the bottom
  • Formats tasks as markdown checkboxes (- [ ] task)
  • Subtasks are indented with 2 spaces

• If TASKS_FILE_PATH is not set (remote mode):

  • Sends tasks to Discord as a file attachment
  • Filename format: tasks_to_add_YYYYMMDD_HHMMSS.md (UTC-8 timestamp)

Example usage in MCP client:

"Add these tasks to my todo list: Review the PR, Write documentation, Test the feature"
"Add these items to my checklist: [list items]"

How It Works

Markdown Notes (send_markdown_to_discord)

1. Receives content and optional title
2. Formats as markdown (adds title as # Title if provided)
3. Creates a markdown file in memory
4. Sends to Discord as a file attachment
5. Optionally saves locally if LOCAL_FILE_PATH is configured

Task Management (add_tasks)

1. Receives array of task items
2. Formats as markdown checkboxes (- [ ] task)
3. Detects subtasks (items with leading spaces/tabs) and indents them
4. Local mode (if TASKS_FILE_PATH is set):
   • Reads existing tasks from file
   • Appends new tasks
   • Writes back to file
5. Remote mode (if TASKS_FILE_PATH is not set):
   • Generates timestamped filename (UTC-8)
   • Sends to Discord as file attachment

Environment Variables

Docker Deployment

Using Docker Compose (Recommended)

1. Create a .env file with your configuration (see above)

2. Build and run with Docker Compose:

docker-compose up -d

1. View logs:

docker-compose logs -f

1. Stop the container:

docker-compose down

Using Docker Directly

1. Build the Docker image:

docker build -t discord-markdown-notes-mcp .

1. Run the container:

docker run -it --rm \
  -e DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your_webhook_id/your_webhook_token \
  -e LOCAL_FILE_PATH=/app/notes \
  -e TASKS_FILE_PATH=/app/tasks.md \
  -p 3000:3000 \
  discord-markdown-notes-mcp

Or use a .env file:

docker run -it --rm \
  --env-file .env \
  -p 3000:3000 \
  discord-markdown-notes-mcp

Docker Notes

• The HTTP server runs on port 3000 inside the container
• Port 3000 is exposed and mapped to your host machine
• Environment variables can be passed via -e flags, --env-file, or in docker-compose.yml
• The container runs the built TypeScript code from the dist directory
• You can access the server at http://localhost:3000 when running with Docker

Example Usage

Using MCP Client (Recommended)

When connected via an MCP client like Cursor or Claude Desktop, you can use natural language:

For markdown notes:

• "Create a markdown note about today's meeting"
• "Save this summary as a markdown file"
• "Send this document to Discord"

For tasks:

• "Add these tasks to my todo list: [list tasks]"
• "Add these items to my checklist: [list items]"
• "Add these action items: [list items]"

Using curl (for testing)

# Send a markdown note
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "send_markdown_to_discord",
      "arguments": {
        "prompt": "This is a test note with **markdown** formatting.",
        "title": "Test Note"
      }
    },
    "id": 1
  }'

# Add tasks
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "add_tasks",
      "arguments": {
        "items": ["Review PR", "Write docs", "Test feature"]
      }
    },
    "id": 2
  }'

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

License

ISC