Ubersuggest MCP - Standalone Node.js Runner

Implementasi standalone Model Context Protocol (MCP) server untuk Ubersuggest yang berjalan sepenuhnya di komputer lokal menggunakan database SQLite (node:sqlite) dan Playwright lokal, tanpa dependensi cloud.

Fitur Utama

• Zero Cloud Infrastructure: Didesain sepenuhnya untuk dijalankan secara lokal di PC Anda.
• Fast Local Caching: Data Site Audit disimpan dalam cache SQLite lokal selama 24 jam. Panggilan berulang selesai dalam < 10ms.
• Auto-Formatting: Menyajikan data teknis audit dalam format Markdown ringkas yang ramah terhadap LLM/klien MCP.
• Playwright Reconnect: Otomatis memperbarui session/cookie Ubersuggest Anda menggunakan browser Playwright lokal.

---

Cara Install (One-Line Setup)

Anda dapat menginstal dan mengonfigurasikan server MCP ini secara otomatis langsung dari GitHub menggunakan satu baris perintah berikut:

npx github:muizzahabibi/ubersuggest-mcp-node

Perintah ini akan secara otomatis:

1. Meminta lokasi folder instalasi permanen di komputer Anda (default: ~/ubersuggest-mcp-node).
2. Mengkloning repositori ini secara otomatis.
3. Memasang dependensi Node.js & browser Playwright (Chromium).
4. Melakukan build TypeScript.
5. Membuka wizard interaktif untuk mendaftarkan server ke klien MCP pilihan Anda (Claude Desktop, Cursor, Claude Code CLI, Codex CLI, Antigravity IDE/CLI, atau semuanya!).

Jika Anda sudah mengkloning repositori ini secara manual, Anda bisa menjalankan konfigurasi interaktif langsung dari dalam folder proyek dengan perintah:

npm install && npx playwright install chromium && npm run build && npm run setup

---

Panduan Penyetelan Manual

1. Claude Desktop

Penyetelan manual pada berkas konfigurasi Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ubersuggest-node": {
      "command": "node",
      "args": [
        "--experimental-sqlite",
        "--env-file=/PATH/TO/ubersuggest-mcp-node/.env",
        "/PATH/TO/ubersuggest-mcp-node/dist/server.js",
        "--stdio"
      ]
    }
  }
}

(Ganti /PATH/TO/ dengan path absolut direktori proyek ini).

2. Cursor

1. Buka Cursor Settings -> Features -> MCP.
2. Klik + Add New MCP Server.
3. Isi parameter berikut:
   • Name: ubersuggest-node
   • Type: stdio
   • Command: node
   • Arguments: --experimental-sqlite --env-file="/PATH/TO/ubersuggest-mcp-node/.env" "/PATH/TO/ubersuggest-mcp-node/dist/server.js" --stdio
4. Klik Save dan restart Cursor.

3. Codex CLI

Wizard npm run setup dapat mengonfigurasi Codex otomatis. Jika ingin manual, tambahkan blok berikut ke ~/.codex/config.toml:

[mcp_servers.ubersuggest_node]
enabled = true
command = "node"
args = ["--experimental-sqlite", "--env-file=/PATH/TO/ubersuggest-mcp-node/.env", "/PATH/TO/ubersuggest-mcp-node/dist/server.js", "--stdio"]

Gunakan nama ubersuggest_node agar bisa berjalan berdampingan dengan MCP Ubersuggest HTTP/remote lain.

4. Antigravity IDE/CLI

Wizard npm run setup dapat mengonfigurasi Antigravity otomatis. Jika ingin manual, tambahkan blok berikut ke ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "ubersuggest_node": {
      "command": "node",
      "args": [
        "--experimental-sqlite",
        "--env-file=/PATH/TO/ubersuggest-mcp-node/.env",
        "/PATH/TO/ubersuggest-mcp-node/dist/server.js",
        "--stdio"
      ]
    }
  }
}

Untuk config per-project Antigravity, gunakan isi yang sama di .agents/mcp_config.json.

---

Menghubungkan Akun Ubersuggest (Penting)

Sebelum MCP dapat digunakan, Anda harus mengisi sesi login Ubersuggest Anda ke database lokal.

1. Jalankan API server lokal:

   npm run dev
   

2. Buka browser dan akses halaman panduan lokal:

   http://127.0.0.1:8787/guide
   

3. Lakukan login menggunakan akun MCP Anda (kredensial default: username admin, password admin-secure-password-123).
4. Ikuti instruksi di layar untuk menempelkan Cookies browser Anda dari situs app.neilpatel.com. Sesi akan disimpan di SQLite lokal (ubersuggest.db) dengan enkripsi aman.
5. Selesai! Matikan server API (Ctrl + C) dan jalankan MCP client Anda.

---

Daftar Tools MCP yang Tersedia

1. ubersuggest_subscription — Mengambil status langganan Ubersuggest Anda.
2. ubersuggest_projects — Mengambil daftar proyek website yang dipantau di akun Anda.
3. ubersuggest_domain_overview — Mengambil metrik lalu lintas (traffic), organic keywords, backlinks, dan SEO score domain tertentu.
4. ubersuggest_domain_top_pages — Mengambil halaman dengan kunjungan tertinggi dari suatu domain.
5. ubersuggest_traffic_estimation — Mengambil riwayat estimasi traffic bulanan.
6. ubersuggest_keyword_research — Melakukan riset ide kata kunci (volume, SEO difficulty, CPC, paid difficulty).
7. ubersuggest_seo_opportunities — Mengambil daftar peluang perbaikan SEO spesifik.
8. ubersuggest_site_audit — Melakukan technical audit website (Core Web Vitals + Crawl Issues).
9. ubersuggest_auth_reconnect — Melakukan penyambungan ulang sesi Ubersuggest.
10. ubersuggest_auth_logout — Logout sesi Ubersuggest dari database lokal.