Quick Start

Get textrawl running in 5 minutes.

PrerequisitesCopy Anchor Link

• Node.js 22+ (Download)
• PostgreSQL with pgvector (Neon, Supabase, RDS, or self-hosted)
• Embedding provider: OpenAI, Google AI, or Ollama for local embeddings

Step 1: Clone and InstallCopy Anchor Link

git clone https://github.com/jeffgreendesign/textrawl.git
cd textrawl
pnpm install

Step 2: Run SetupCopy Anchor Link

The setup script creates your .env file with secure defaults:

pnpm run setup

You'll be prompted for:

• DATABASE_URL (use a pooled Postgres connection string for the server)
• Embedding provider credentials, or Ollama settings for local embeddings
• API_BEARER_TOKEN for authenticated clients

Step 3: Initialize DatabaseCopy Anchor Link

Run the schema against your configured database:

psql "$DATABASE_URL" -f scripts/setup-db.sql

Use the provider-specific schema if needed (setup-db-ollama.sql, setup-db-ollama-v2.sql, or setup-db-google.sql). Then run the security script:

psql "$DATABASE_URL" -f scripts/security-rls.sql

Supabase is supported as one Postgres option, but never expose Supabase service-role credentials to browser, desktop, or other client code. Prefer a pooled DATABASE_URL used only by the server.

Step 4: Start the ServerCopy Anchor Link

pnpm run dev

Server runs at http://localhost:3000

Step 5: Connect a ClientCopy Anchor Link

textrawl supports multiple access methods. Choose whichever suits your workflow:

Web DashboardCopy Anchor Link

Open http://localhost:3000 in your browser. You should see the knowledge explorer where you can browse documents, upload files, and explore your knowledge base.

Claude Desktop (MCP)Copy Anchor Link

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

{
  "mcpServers": {
    "textrawl": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Restart Claude Desktop to connect.

REST APICopy Anchor Link

Query textrawl directly over HTTP (the setup script generates API_BEARER_TOKEN in your .env):

curl -H "Authorization: Bearer $API_BEARER_TOKEN" \
  "http://localhost:3000/api/documents"

Verify It WorksCopy Anchor Link

Using the DashboardCopy Anchor Link

Open http://localhost:3000. Try uploading a document or creating a note from the dashboard.

Imported documents, extracted memories, and conversation summaries remain in your configured database/storage until deleted.

For production:

• Set API_BEARER_TOKEN.
• Restrict CORS.
• Avoid importing third-party/private data without consent.

Using the REST APICopy Anchor Link

# Check health (no auth required)
curl http://localhost:3000/health

# Search for documents
curl -H "Authorization: Bearer $API_BEARER_TOKEN" \
  "http://localhost:3000/api/search?q=test&limit=5"

Using MCP InspectorCopy Anchor Link

pnpm run inspector

Opens a web UI at http://localhost:5173 to test tools interactively.

In Claude DesktopCopy Anchor Link

Ask Claude:

"Use the search tool to find documents about getting started"

If no documents exist yet, add a test note:

"Use add_note to create a note titled 'Test Note' with content 'This is a test of textrawl'"

Then search for it:

"Search for 'test' in my knowledge base"

Next StepsCopy Anchor Link

• Add your first documents with CLI tools
• Configure embeddings for Ollama (local)
• Database requirements for compute tier and sizing
• Deploy to production with Docker

TroubleshootingCopy Anchor Link

"Database not configured"Copy Anchor Link

Verify your .env has a valid DATABASE_URL:

DATABASE_URL=postgresql://user:pass@ep-xxx-pooler.neon.tech/textrawl?sslmode=require

"OpenAI not configured"Copy Anchor Link

Ensure OPENAI_API_KEY is set in .env

Claude can't connectCopy Anchor Link

1. Verify server is running: curl http://localhost:3000/health
2. Check Claude Desktop config path is correct
3. Restart Claude Desktop after config changes