Which integrations are available for this server?

Enables interaction with the Prompteka macOS application, allowing AI assistants to manage and organize local prompt libraries directly on the system. Connects directly to the Prompteka SQLite database to provide programmatic access for reading, searching, and updating stored AI prompts and folders.

How do I use Prompteka MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Prompteka MCP Server Search my library for my 'Python Refactoring' prompt" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Prompteka MCP Server

Model Context Protocol server for Prompteka - enables AI assistants to read and write your prompt library.

TL;DR

What is Prompteka? Prompteka is a native macOS app (available on the App Store) that lets you organize, search, and manage your AI prompt library locally on your Mac. Think of it as a smart folder system for all your prompts with tagging, emojis, colors, and full-text search.

What does this MCP Server do? This server enables any MCP-compatible AI assistant (Claude Desktop, Cursor, and others) to directly access and manage your Prompteka library programmatically. Instead of manually copying prompts in and out, your AI assistant can:

📖 Read and search your entire prompt library
✍️ Create new prompts and organize them
🎨 Update existing prompts with new content
🗑️ Organize your library by moving prompts between folders

How do they work together?

Your Mac ├── Prompteka App (native macOS app on App Store) │ └── SQLite Database at ~/Library/Application Support/prompteka/prompts.db │ ↑ (reads/writes) └── This MCP Server (Node.js process) └── Connects to same database via MCP protocol ↑ (AI assistants read/write through MCP)

The MCP server connects directly to your Prompteka database, so changes made by the AI are persisted immediately to the database. Refresh the Prompteka app to see updates in the UI. No syncing, no copying - single source of truth.

Installation:

Have Prompteka app installed
npm install -g prompteka-mcp (once published)
Configure your MCP client (Claude Desktop, Cursor, etc.)
Start using: "Add this prompt to my Security folder"

Ready to dive in? Jump to Workflow Scenarios to see what you can do with MCP + Prompteka.

🚨 Regular Backups Recommended
Your prompt library is valuable! We strongly encourage you to regularly backup your Prompteka library. Backups are fully supported through the Prompteka app itself and protect you against accidental deletions or data loss. You can export your entire library as a backup file directly from Prompteka - this is a safe, built-in feature that ensures you never lose your prompts.

Features

✅ Read Your Prompts List, search, and retrieve all your prompts and folders with full content.

✅ Create & Organize Create new prompts in specific folders with emojis, colors, and links.

✅ Update & Delete Modify existing prompts or organize your library through AI.

✅ Safe & Local-Only Operates entirely locally in ~/Library/Application Support/prompteka/. No network calls, no telemetry, no data sent anywhere.

✅ Independent Operation Works with or without Prompteka app running. Direct database access means zero dependencies.

How It Works

Integration with Prompteka

The MCP server connects directly to the same SQLite database that the Prompteka app uses. This means:

Database-Level Persistence: Changes made by the AI are committed to the database immediately (< 10ms)
Single Source of Truth: The local SQLite database is the only copy of your data
Concurrent Safe: Both Prompteka app and MCP server can operate simultaneously without conflicts
App-Independent: The MCP server doesn't depend on the Prompteka app being running
UI Refresh Required: Refresh the Prompteka app (⌘R or Refresh button) to see changes in the UI

Architecture Overview

The Prompteka MCP Server operates in two modes:

Read Operations (Fast, Direct Database Access)

Connects directly to your Prompteka SQLite database at ~/Library/Application Support/prompteka/prompts.db
Uses WAL (Write-Ahead Logging) mode for safe concurrent access with Prompteka app
Returns results in < 100ms
Does NOT interfere with Prompteka app operations

Write Operations (Immediate Database Persistence)

Writes directly to Prompteka SQLite database using WAL mode
Uses atomic transactions with full ACID guarantees
Changes committed immediately (< 10ms)
Available to other MCP read operations and SQLite clients immediately
Prompteka app UI updates upon refresh (⌘R or Refresh button)
SQLite handles concurrent access safely

This unified approach ensures:

✅ Sub-10ms database persistence (immediate data availability)
✅ No app dependency - MCP server operates standalone
✅ Safe concurrent read-write with WAL mode
✅ Automatic atomic rollback on errors
✅ Zero orphaned operations or cleanup needed
✅ Single source of truth - the local SQLite database

Database Location

Prompteka stores its data at:

~/Library/Application Support/prompteka/prompts.db

The MCP server accesses this file to read your prompts and folders.

Write Operations (Direct Database)

When you use write tools (create_prompt, update_prompt, etc.), here's what happens:

Validation: MCP server validates your input against JSON schemas (local, instant)
Transaction: Opens atomic SQLite transaction with implicit locking
Execution: Executes INSERT/UPDATE/DELETE operation against prompts.db
Commit: Transaction commits automatically (or rolls back if error)
Response: Returns success/error response immediately (< 10ms typical)
Visibility: Changes are immediately available to:
- Other MCP read operations (instant)
- Prompteka app database queries (instant)
- Prompteka app UI (upon refresh with ⌘R or Refresh button)
- Any other SQLite clients accessing the database (instant)

This all happens in < 10ms at the database level. No app required to be running. Refresh the Prompteka app to see changes reflected in the UI.

Quick Reference: All Tools

Tool	Type	Description
`list_folders`	Read	Get all folders with metadata
`list_prompts`	Read	Get prompts from folder (paginated)
`get_prompt`	Read	Get single prompt by ID
`search_prompts`	Read	Full-text search across prompts
`health_check`	Read	Verify MCP server and database operational
`create_prompt`	Write	Create new prompt in folder
`update_prompt`	Write	Modify existing prompt
`delete_prompt`	Write	Delete prompt (idempotent)
`create_folder`	Write	Create new folder
`update_folder`	Write	Modify folder properties
`delete_folder`	Write	Delete folder with safety checks
`move_prompt`	Write	Move prompt to different folder

Response Times:

Read tools: < 100ms (direct database)
Write tools: < 10ms (direct database, atomic transactions)

All operations are logged with detailed status, errors, and timing information.

Installation

Prerequisites

Prompteka app from the App Store installed on your Mac
- (Just needs to have been opened once to create the database)
- The app does NOT need to stay running - the MCP server accesses the database directly
Node.js 18.0.0 or newer
npm 9.0.0 or newer

Note: You can have Prompteka app and this MCP server running simultaneously with zero conflicts. They share the same SQLite database safely via WAL mode.

Check your versions:

node --version # Should be 18.0.0 or higher npm --version # Should be 9.0.0 or higher

Step 1: Install Prompteka MCP Server

Option A: From npm (once published)

npm install -g prompteka-mcp

Option B: From source (development)

# Clone the repository git clone https://github.com/webdevguyrg/prompteka-mcp.git cd prompteka-mcp # Install dependencies npm install # Build TypeScript to JavaScript npm run build # Install globally on your system npm install -g . # Verify installation which prompteka-mcp # Should show path to installed binary

Step 2: Configure Your MCP Client

The MCP server is now installed. Next, configure your MCP-compatible AI tool to use it.

Add this server configuration to your MCP client:

{ "mcpServers": { "prompteka": { "command": "prompteka-mcp", "args": [], "env": { "LOG_LEVEL": "info" } } } }

Common MCP client configuration locations:

Client	Config File Location
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%AppData%\Claude\claude_desktop_config.json`
Cursor	Check Settings → MCP
Other clients	Refer to your client's MCP documentation

After adding the configuration, fully restart your MCP client (quit and reopen, not just close the window).

Step 3: Verify Installation

Verify the binary is installed:

which prompteka-mcp # Should show path to installed binary

Advanced Configuration

Custom Database Path

If Prompteka is installed in a non-standard location:

export PROMPTEKA_DB_PATH="/custom/path/prompts.db" prompteka-mcp

Or in your MCP config:

{ "mcpServers": { "prompteka": { "command": "prompteka-mcp", "env": { "PROMPTEKA_DB_PATH": "/custom/path/prompts.db" } } } }

Logging Level

Control verbosity:

{ "mcpServers": { "prompteka": { "command": "prompteka-mcp", "env": { "LOG_LEVEL": "debug" # or: info, warn, error } } } }

Log output appears in your MCP tool's console.

Available Tools (12 Total)

Read-Only Tools (5 tools, Direct Database Access)

list_folders Get all your folders with metadata (name, parent hierarchy, timestamps).

list_prompts Get prompts from a specific folder with pagination.

get_prompt Get full details of a single prompt by ID.

search_prompts Full-text search across all prompt titles and content.

health_check Verify MCP server and database are operational. Returns server version and connectivity status.

Write Tools (7 tools, Direct Database Access)

create_prompt Create a new prompt in a folder with emoji, color, and optional URL. Defaults to 🤖 emoji and blue color if not specified.

update_prompt Modify an existing prompt (title, content, folder, emoji, color, URL).

delete_prompt Delete a prompt (requires explicit confirmDelete=true safety confirmation, idempotent - safe to retry).

create_folder Create a new folder with optional parent folder for nesting.

update_folder Rename or reorganize a folder.

delete_folder Delete a folder (requires explicit confirmDelete=true safety confirmation).

Can delete empty folders instantly
Can delete folder with all contents using recursive=true
AI will ask for confirmation before deleting folders with contents

move_prompt Move a prompt to a different folder.

Move single prompt to new folder
Target can be any folder (or null for root)
Updates folder references automatically

Response Times

Read operations: < 100ms (direct database)
Write operations: < 10ms (direct database, atomic transactions)

Use Cases

UC1: Capture Prompts Quickly

An MCP client can automatically save generated prompts directly to your Prompteka library without manual copy-paste.

UC2: Organize Your Library

MCP clients can help organize and reorganize your prompt library, move prompts between folders, and apply consistent tagging.

UC3: Audit Your Prompts

Analyze your prompt library - count prompts by color, folder, age; identify unused prompts; find duplicates.

UC4: Clone & Customize

Create variations of existing prompts with MCP integration - modify content, category, metadata in one operation.

UC5: Backup & Migrate

Use the Prompteka app's built-in export feature to backup your entire library or migrate between systems. The MCP server provides read access for automation purposes, but full backup/restore operations are safely handled by the Prompteka app itself to ensure data integrity.

UC6: Batch Operations

Perform bulk changes - update colors, reorganize folders, or apply metadata to multiple prompts at once.

Workflow Scenarios & Support Matrix

Real-world scenarios showing different states (no prompts, one prompt, multiple prompts) and whether they're currently supported:

Legend:

✨ = Create new prompt/folder(s)
📖 = Read/search/retrieve existing
🔨 = Modify/update existing
🗑️ = Delete
✅ = System check

Scenario	User Action	Folder State	Prompt State	What Happens	Currently Supported
✨ Save Generated Prompt	"Save this as 'Security Checklist' in Security folder"	Folder exists	❌ New	AI calls `create_prompt` with title, content, folderId	✅ YES
✨ Save Without Folder	"Save that as 'Quick Test'"	❌ Must choose or create	❌ New	AI calls `list_folders`, user picks, then `create_prompt`	✅ YES
✨✨ Save & Create Folder	"Save as 'Testing' in new folder 'QA'"	❌ Doesn't exist	❌ New	AI calls `create_folder`, then `create_prompt`	✅ YES
📖 Find & Run Prompt	"Run my code review prompt"	✅ Single exists	✅ Single match	AI calls `search_prompts("code review")`, gets result, executes it	✅ YES
📖 Ambiguous Search	"Run code review prompt"	✅ Exists	✅ Multiple matches (General, Security, Performance)	AI calls `search_prompts`, shows numbered list, user picks, executes	✅ YES
📖 Run from Folder	"Run all testing prompts"	✅ Testing folder exists	✅ Multiple (5 prompts)	AI calls `list_prompts(folderId)`, shows all 5, user selects or runs all sequentially	✅ YES
📖 Search All Prompts	"Find prompts about authentication"	N/A	✅ Found 3 matches	AI calls `search_prompts("authentication")`, shows: Password Auth, OAuth, SAML	✅ YES
✨ Save Prompt Variation	"Save this variant as 'Code Review v2'" in existing folder	✅ Exists	❌ New (variation)	AI calls `create_prompt` in same folder, user can now switch between v1 and v2	✅ YES
🔨 Update Existing Prompt	"Update my security prompt with this new content"	✅ Exists	✅ Single found	AI calls `search_prompts`, confirms ID, calls `update_prompt`	✅ YES
🔨 Move Prompt	"Move this prompt from Personal to Work"	✅ Both exist	✅ Found	AI calls `move_prompt` to change folderId	✅ YES
✨✨✨ Organize by Folder	"Create folders for Work, Personal, Testing"	❌ Don't exist	N/A	AI calls `create_folder` 3 times with different names	✅ YES
📖 List Everything	"Show me all my prompts organized by folder"	✅ Multiple	✅ Multiple	AI calls `list_folders`, then `list_prompts` for each folder	✅ YES
📖 Batch Review	"Run all security prompts against this code"	✅ Security folder exists	✅ Multiple (5 security prompts)	AI calls `list_prompts(securityFolderId)`, runs each one, compares results	✅ YES
📖 Prompt Chain	"Walk me through: Setup > Configure > Deploy"	✅ Exists	✅ 3 prompts in sequence	AI calls `search_prompts` for each, executes in order with context passed between	✅ YES
🗑️ Delete Old Prompt	"Remove the old password prompt"	✅ Exists	✅ Single found	AI calls `search_prompts("password")`, confirms ID, calls `delete_prompt`	✅ YES
🔨 Rename Folder	"Rename Security folder to SecOps"	✅ Exists	N/A	AI calls `update_folder` with new name	✅ YES
🗑️ Delete Empty Folder	"Clean up old Test folder"	✅ Empty folder exists	N/A (folder empty)	AI calls `delete_folder`	✅ YES
🗑️ Delete with Contents	"Remove Testing folder and all prompts in it"	✅ Exists with prompts	✅ Multiple	AI asks user to confirm, then calls `delete_folder(recursive=true, confirmDelete=true)`	✅ YES (with confirmation)
✅ Health Check	"Is the MCP server running?"	N/A	N/A	AI calls `health_check`, gets server version and connectivity status	✅ YES

Key Workflow Patterns

Pattern 1: Save Iteration

User: "Save that as 'Review v2' in Security" AI: list_folders() → create_prompt(title, content, folderId) Result: New version saved, can switch between v1 and v2 later

Support: ✅ Full (create_prompt tool)

Pattern 2: Search & Execute

User: "Run my code review prompt" AI: search_prompts("code review") → If 1 match: execute → If multiple: show numbered list, user picks Result: Prompt retrieved and executed instantly

Support: ✅ Full (search_prompts + get_prompt tools)

Pattern 3: Batch Run

User: "Run all security prompts against this code" AI: list_prompts(securityFolderId) → shows 5 prompts AI: For each prompt: execute sequentially Result: Comprehensive security analysis from multiple angles

Support: ✅ Full (list_prompts + get_prompt tools)

Pattern 4: Organize

User: "Move testing prompts to a QA folder" AI: search_prompts() → create_folder("QA") → move_prompt() × N Result: Prompts reorganized, visible in Prompteka app immediately

Support: ✅ Full (search_prompts + create_folder + move_prompt tools)

Security & Privacy

Network & Data

Strictly local-only: No network calls whatsoever
No telemetry: No analytics, no error reporting
Your data stays yours: All operations within ~/Library/Application Support/prompteka/
No copies: Prompt data never leaves your machine
Sandbox-safe: Works within macOS sandbox restrictions

Validation & Safety

All inputs validated before writing
Symlinks rejected (path traversal protection)
File permissions: 0600 (user-only)
Idempotent writes (safe to retry)

Logging

Logs are structured JSON (no PII):

{ "timestamp": "2025-12-09T10:30:45.123Z", "tool": "create_prompt", "operationId": "...", "durationMs": 145, "status": "success" }

Prompt content: Never logged (only length tracked)
Emails/URLs: Redacted
Debug logs available with LOG_LEVEL=debug

Troubleshooting

"Database file not found"

This means the Prompteka app hasn't created its database yet. Ensure Prompteka is installed and has been opened at least once:

# Download from App Store: https://apps.apple.com/app/prompteka/id6738107425 # Or open if already installed: open /Applications/Prompteka.app

Once you've opened Prompteka once, check the database exists:

ls -la ~/Library/Application\ Support/prompteka/prompts.db

"Database is locked" or "SQLITE_BUSY"

The database write lock timed out after 5 seconds. This is rare but can happen if:

Prompteka app is performing a large operation
Database corruption scan is running
Another MCP client is also writing

Solution: Retry the operation. Automatic retry is built-in, but if you still see this error:

# Check database file exists and is readable ls -la ~/Library/Application\ Support/prompteka/prompts.db*

Changes via MCP not showing in Prompteka app

If you've made changes to your prompts through MCP (via Claude, Cursor, etc.) and the Prompteka app is open, you may need to refresh the app to see the latest data.

Solution: Refresh the Prompteka app:

Click the "Refresh" button in the top toolbar
Keyboard shortcut: Press ⌘R (Command+R)

The MCP server writes directly to the database, so changes are persistent immediately. The app refresh simply reloads the UI to display the updated data.

API Reference

See documentation/PRD.md for complete API specification including:

Tool schemas and validation rules
Error taxonomy with recovery strategies
Database contract (WAL mode, transactions, concurrency)
Concurrency & limits policy
Testing strategy

Development

Building from Source

npm install npm run build npm run type-check npm test

Development Mode

npm run dev

Code Quality

npm run lint npm run test:coverage

Architecture

The MCP server uses a read-direct, write-direct pattern with SQLite WAL mode:

┌─────────┐ │ AI │ (MCP-compatible assistant) └────┬────┘ │ MCP Protocol ▼ ┌─────────────────────────┐ │ Prompteka MCP Server │ ├─────────────────────────┤ │ Read Operations (5): │ (Direct DB access) │ ├─ list_folders │ < 100ms │ ├─ list_prompts │ │ ├─ get_prompt │ │ ├─ search_prompts │ │ └─ health_check │ │ │ │ Write Operations (7): │ (Direct DB access) │ ├─ create_prompt │ < 10ms │ ├─ update_prompt │ (atomic transactions) │ ├─ delete_prompt │ │ ├─ create_folder │ │ ├─ update_folder │ │ ├─ delete_folder │ │ └─ move_prompt │ └────┬──────────────────┬─┘ │ Direct Read │ Direct Write │ (WAL mode) │ (WAL mode) ▼ ▼ ┌──────────────────────────────────────┐ │ Prompteka SQLite Database │ ├──────────────────────────────────────┤ │ WAL File: prompts.db-wal │ │ Shared Memory: prompts.db-shm │ │ Validation & Persistence │ └──────────────────────────────────────┘

Minimum Requirements

Requirement	Version	Notes
macOS	12.0+ (Monterey)	Prompteka requirement
Node.js	18.0.0+	LTS, ESM support
npm	9.0.0+	Bundled with Node 18+
Prompteka	1.6.2+	WAL mode support

Contributing

This is a public project. Contributions welcome!

Fork the repository
Create a feature branch (git checkout -b feature/amazing-thing)
Commit changes with clear messages
Push to branch (git push origin feature/amazing-thing)
Open a Pull Request

License

MIT - See LICENSE file for details

Support & Resources

About Prompteka

Official Website: prompteka.net
App Store: Prompteka on Mac App Store
Prompteka Support: prompteka.net/support.html
Privacy Policy: prompteka.net/privacy-policy.html

About This MCP Server

Documentation: See documentation/PRD.md for complete API specification
GitHub Issues: Report bugs or request features
Contributing: See CONTRIBUTING.md for developer guidelines

Privacy Policy

The Prompteka MCP Server is local-only and does not collect any data. For Prompteka app privacy details, see: https://prompteka.net/privacy-policy.html

Made with ❤️ for Prompteka users

Questions? Open an issue on GitHub.