idea-basin-mcp

MCP server for Idea Basin — a semantic knowledge graph with vector search, hierarchical organization, and automatic content ingestion.

Gives Claude (and any MCP-compatible AI assistant) the ability to search, browse, and save to your personal knowledge base.

How it works

flowchart LR
    subgraph client["AI Assistant"]
        Claude["Claude / Any MCP Client"]
    end

    subgraph mcp["idea-basin-mcp"]
        direction TB
        T1["search_knowledge"]
        T2["browse_nodes"]
        T3["get_node"]
        T4["save_resource"]
        T5["fetch_and_save"]
    end

    subgraph basin["Idea Basin Server :3500"]
        API["REST API"]
        Embed["Embedder"]
        Scraper["Scraper"]
    end

    subgraph storage["Storage"]
        PG[("PostgreSQL + pgvector")]
    end

    Claude -- "stdio / JSON-RPC" --> mcp
    mcp -- "HTTP" --> API
    API --> Embed
    API --> Scraper
    API --> PG

Tools

Tool	Description
search_knowledge	Semantic similarity search across all knowledge chunks
browse_nodes	Browse the knowledge graph tree structure (3 levels deep)
get_node	Inspect a node with its children and resources
save_resource	Save a note, research, link, code, or idea to a node
fetch_and_save	Fetch a URL (web page, YouTube, GitHub, arXiv, PDF) and save it

Prerequisites

A running Idea Basin server (default: http://localhost:3500).

Install

Claude Code

claude mcp add idea-basin -- node /path/to/idea-basin-mcp/build/index.js

Or with a custom Basin URL:

claude mcp add idea-basin -e IDEA_BASIN_URL=http://localhost:3500 -- node /path/to/idea-basin-mcp/build/index.js

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "idea-basin": {
      "command": "node",
      "args": ["/path/to/idea-basin-mcp/build/index.js"],
      "env": {
        "IDEA_BASIN_URL": "http://localhost:3500"
      }
    }
  }
}

npm (once published)

npx idea-basin-mcp

Configuration

Env var	Default	Description
IDEA_BASIN_URL	http://localhost:3500	Base URL of your Idea Basin server

Development

npm install
npm run build    # TypeScript → build/
npm run dev      # Watch mode

License

MIT