📝 Joplin MCP Server

Connect Joplin notes to AI — Claude Desktop, opencode, Cursor, VS Code Copilot

اربط ملاحظات Joplin بالذكاء الاصطناعي عبر Model Context Protocol

🚀 ما هو هذا المشروع / What is this project

Joplin MCP Server هو خادم Model Context Protocol (MCP) يربط أدوات الذكاء الاصطناعي بملاحظاتك في Joplin عبر REST API المحلي (المنفذ 41184).

An MCP server that gives AI assistants direct, read/write access to your Joplin notes through Joplin's local REST API — no cloud, no sync, everything stays on your machine.

✅ 20 أداة جاهزة | يعمل محلياً 100% | يدعم العربية و UTF-8 | سطر واحد للتشغيل

✨ المزايا / Features

• 🔌 تكامل مع كل عملاء MCP: Claude Desktop, opencode, Cursor, VS Code Copilot

• 📂 إدارة كاملة: قراءة، إنشاء، تعديل، حذف، نقل الملاحظات والمجلدات

• 🔍 بحث نصي كامل عبر /search

• ✅ دعم المهام (Todos) مع فلترة حسب الحالة

• 🏷️ دعم الوسوم (Tags)

• ⚡ عمليات جماعية (Bulk): نقل/حذف/وسم دفعة واحدة

• 🛡️ أمان: التوكن من متغير بيئة فقط، لا يُكتب في الكود

• 🌍 UTF-8 كامل — يعمل بسلاسة مع العربية وكل اللغات

Related MCP server: Joplin MCP Server

📦 المتطلبات المسبقة / Prerequisites

تفعيل Web Clipper:

1. افتح Joplin → Tools → Options → Web Clipper

2. فعّل Enable Web Clipper Service

3. تأكد أن المنفذ 41184 ظاهر في الإعدادات

4. انسخ Authorization token من Advanced options

🛠️ التركيب خطوة بخطوة / Installation

1️⃣ اجلب المشروع

git clone https://github.com/<your-username>/joplin-mcp-server.git
cd joplin-mcp-server

2️⃣ ثبّت المتطلبات

pip install -r requirements.txt

3️⃣ اضبط متغيرات البيئة

cp .env.example .env          # ثم حرّر الملف وضع توكنك
# أو مباشرة في البيئة:
export JOPLIN_TOKEN="YOUR_TOKEN_HERE"        # Linux / macOS
$env:JOPLIN_TOKEN = "YOUR_TOKEN_HERE"        # Windows PowerShell

4️⃣ أضف السيرفر إلى عميلك / Configure your AI client

🤖 Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "joplin": {
      "command": "python",
      "args": ["-m", "joplin_server"],
      "env": { "JOPLIN_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}

⚡ opencode — opencode.json (قسم mcp)

{
  "mcp": {
    "joplin": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "joplin_server"],
      "env": { "JOPLIN_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}

🧩 VS Code Copilot — .vscode/mcp.json

{
  "servers": {
    "joplin": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "joplin_server"],
      "env": { "JOPLIN_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}

💡 قد تحتاج إلى المسار الكامل لـ python (مثل C:/Python310/python.exe) حسب إعدادات PATH. أعد تشغيل العميل بعد التعديل.

🔬 اختبار السيرفر / Testing

1. اختبار Joplin مباشرة (تأكد أن Web Clipper يعمل):

curl "http://127.0.0.1:41184/ping?token=YOUR_TOKEN_HERE"
# المتوقع: JoplinClipperServer

2. فحص المنفذ:

Test-NetConnection 127.0.0.1 -Port 41184

3. تشغيل السيرفر:

python -m joplin_server

ثم اطلب من مساعد الذكاء الاصطناعي استدعاء أداة joplin_ping — إذا أعادت JoplinClipperServer فكل شيء يعمل.

🛠️ الأدوات المتاحة / Available Tools (20)

كل أداة تعيد JSON منسّقاً: {"success": true, "id": "...", "data": {...}}

🧑‍💻 أمثلة استخدام / Usage Examples

"اعرض لي مجلداتي" → joplin_list_folders()

"ابحث عن ملاحظات فيها 'خطة العمل'" → joplin_search_notes(query="خطة العمل")

"أنشئ ملاحظة عن ميزات المشروع في مجلد العمل" → joplin_create_note(title="ميزات", body="...", parent_id="<folder_id>")

"ما المهام غير المكتملة؟" → joplin_list_todos(completed=false)

🧯 استكشاف الأخطاء / Troubleshooting

🔐 ملاحظة أمان / Security

• ⚠️ لا تشارك توكنك أبداً ولا تضعه في الكود أو README

• استخدم متغير بيئة أو ملف .env فقط (وهو مستثنى في .gitignore)

• كل الاتصال محلي على 127.0.0.1 — لا يُرسل أي شيء إلى الإنترنت

🤝 المساهمة في التطوير / Contributing

المساهمات مرحّب بها! اقرأ CONTRIBUTING.md للتفاصيل كاملة.

افكار للمساهمة:

• إضافة أدوات جديدة (المرفقات، الملاحظات المشتركة، التقويم)

• موارد (Resources) و Prompts ضمن MCP

• اختبارات آلية (pytest)

• تحسين التوثيق أو الترجمة

📁 هيكل الملفات / Project Structure

joplin-mcp-server/
├── __main__.py          # نقطة تشغيل `python -m joplin_server`
├── joplin_server.py     # أدوات MCP (FastMCP) — 20 أداة
├── joplin_client.py     # طبقة REST API — مستقلة عن MCP
├── requirements.txt     # mcp + requests
├── CONTRIBUTING.md      # دليل المساهمة
├── LICENSE              # MIT
├── .gitignore
├── .env.example
└── README.md

📄 الترخيص / License

MIT © Joplin MCP Server