Quick Start

Get textrawl running in 5 minutes.

Prerequisites

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 Install

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

Step 2: Run Setup

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 Database

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 Server

pnpm run dev

Server runs at http://localhost:3000

Step 5: Connect a Client

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

Web Dashboard

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)

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

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

Restart Claude Desktop to connect.

REST API

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 Works

Using the Dashboard

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 API

# 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 Inspector

pnpm run inspector

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

In Claude Desktop

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 Steps

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

Troubleshooting

"Database not configured"

Verify your .env has a valid DATABASE_URL:

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

"OpenAI not configured"

Ensure OPENAI_API_KEY is set in .env

Claude can't connect

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

On this page