james-julius/markdrop-mcp-server

 ___  ___              _       _
|  \/  |             | |     | |
| .  . | __ _ _ __ __| |_ __ | | ___  _ __
| |\/| |/ _` | '__/ _` | '_ \| |/ _ \| '_ \
| |  | | (_| | | | (_| | | | | | (_) | |_) |
\_|  |_/\__,_|_|  \__,_|_| |_|_|\___/| .__/
                                     | |
  __  __  ____ ____                  |_|
 |  \/  |/ ___|  _ \
 | |\/| | |   | |_) |
 | |  | | |___|  __/
 |_|  |_|\____|_|

Markdown Knowledge Workspace for Agents

Give Claude Code instant access to shared documentation. Auto-sync markdown files, AI-tag them intelligently, and retrieve them contextually during development.

📑 Table of Contents

• 🎯 What is This?
• 🚀 Installation
• 🛠️ Available Tools
• 💬 How to Use
• 🔄 The Workflow
• 🔧 Troubleshooting
• 🏗️ Architecture
• 🧪 Development

🎯 What is This?

This MCP server connects Claude Desktop to your Markdrop knowledge base. Combined with the Claude Code hook (which auto-captures markdown files), you get a complete RAG-powered development workflow:

• 📝 Hook: Auto-captures markdown docs → Markdrop (with AI tagging)
• 🔍 MCP: Claude retrieves relevant docs when needed → Better context
• 🤖 Result: Your own docs become searchable knowledge for Claude

🚀 Installation

The MCP server is included in your Markdrop installation at markdrop-mcp-server/. Dependencies are already installed.

1. Find Your Markdrop Path

cd /path/to/your/markdrop
pwd  # Copy this path

2. Get Your API Key

Create an API key in Markdrop: Dashboard → API

3. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "markdrop": {
      "command": "node",
      "args": ["/absolute/path/to/your/markdrop/markdrop-mcp-server/index.js"],
      "env": {
        "MARKDROP_API_URL": "http://localhost:3000",
        "MARKDROP_API_KEY": "md_xxxxxxxxxxxx",
        "MARKDROP_PROJECT_ID": "optional-project-id"
      }
    }
  }
}

💡 Pro Tips:

• Use the absolute path to your index.js file
• Set MARKDROP_PROJECT_ID to auto-filter searches to a specific project
• Run multiple MCP instances for multi-project workflows

4. Restart Claude Desktop

Fully quit and restart Claude Desktop. You'll see Markdrop tools appear! ✨

🛠️ Available Tools

🔍 search_pastes

Search through your knowledge base by content, title, tags, or topics.

Parameters:

• query (required) - Search query to match against content and title
• tags (optional) - Array of tags to filter by (e.g., ["architecture", "api"])
• category (optional) - Filter by category
• documentType (optional) - Filter by type (e.g., "architecture", "decision-record")
• limit (optional) - Max results (default: 10)

Try asking:

"Search my pastes for API architecture documentation"

📄 get_paste

Retrieve full content and metadata for a specific paste.

Parameters:

• pasteId (required) - The ID of the paste to retrieve

Try asking:

"Get the full content of paste abc123"

🏷️ list_tags

List all available tags with counts. Great for discovering what's documented.

Parameters:

• category (optional) - Filter tags by category
• minCount (optional) - Minimum pastes per tag (default: 1)

Try asking:

"What tags do I have in my documentation?"

⏰ get_recent_pastes

Get recently created or modified pastes.

Parameters:

• limit (optional) - Max results (default: 10)
• projectId (optional) - Filter by project
• documentType (optional) - Filter by document type

Try asking:

"Show me my recent documentation"

💬 How to Use

Once configured, just ask Claude naturally:

• 💭 "Search my pastes for authentication flow documentation"
• 📚 "What architecture docs do I have?"
• 📝 "Show me recent API documentation I've written"
• 🗄️ "Get the paste about database migrations"

Claude will automatically use these tools to find relevant context from your knowledge base.

🔄 The Workflow

┌─────────────────────────────────────────────────────────┐
│  1. Create docs with Claude Code                       │
│     ↓ (Hook auto-syncs with AI tagging)                │
│  2. Stored in Markdrop                                  │
│     ↓ (Searchable, organized, tagged)                  │
│  3. Ask Claude questions                                │
│     ↓ (MCP retrieves relevant docs)                    │
│  4. Claude responds with YOUR context                   │
│     ↓ (Better answers, project-specific)               │
│  5. Repeat → Build knowledge base over time            │
└─────────────────────────────────────────────────────────┘

This creates a feedback loop where your development docs become searchable context for future work. The more you document, the smarter Claude gets about your project!

🔧 Troubleshooting

🤔 MCP server not showing in Claude Desktop?

• ✅ Check config file: ~/Library/Application Support/Claude/claude_desktop_config.json
• ✅ Verify absolute path to index.js is correct
• ✅ Fully quit and restart Claude Desktop

🚫 Authentication errors?

• ✅ Verify MARKDROP_API_KEY is correct (Dashboard → API)
• ✅ Check Markdrop is running at the specified URL
• ✅ Test manually:

  curl -H "Authorization: Bearer md_xxxxxxxxxxxx" \
       http://localhost:3000/api/pastes/search?query=test
  

🔍 No results when searching?

• ✅ Make sure you've created some pastes first
• ✅ Verify they have tags (use Claude Code hook for auto-tagging)
• ✅ Try a broader search query
• ✅ Check your MARKDROP_PROJECT_ID isn't filtering everything out

🔑 Need an API key?

Create one in Markdrop: Dashboard → API → Create New Key

🏗️ Architecture

┌─────────────────┐
│  Claude Desktop │
└────────┬────────┘
         │ stdio (MCP Protocol)
         ↓
┌─────────────────┐
│   MCP Server    │ (@modelcontextprotocol/sdk)
└────────┬────────┘
         │ HTTP/Bearer Auth
         ↓
┌─────────────────┐
│ Markdrop API    │ (REST API)
└─────────────────┘

Tech Stack:

• @modelcontextprotocol/sdk - Standard MCP protocol implementation
• Stdio Transport - Communicates with Claude via stdin/stdout
• Markdrop REST API - Searches and retrieves pastes
• Bearer Token Auth - Secure API authentication

🧪 Development

Test the server locally:

# Set environment variables
export MARKDROP_API_URL="http://localhost:3000"
export MARKDROP_API_KEY="md_xxxxxxxxxxxx"

# Run server (expects JSON input via stdin)
node index.js

# Or with inspector for debugging
node --inspect index.js

Note: The server logs to stderr, so debug output won't interfere with MCP communication.

📄 License

MIT