Content
# Codehooks.io MCP Server
An MCP (Model Context Protocol) server that provides AI agents with database operations, serverless code deployment, and file management capabilities on the Codehooks.io platform.
## When to Use This MCP vs. CLI Directly
| Environment | Has Terminal? | Recommended Approach |
|-------------|---------------|---------------------|
| Claude Code | Yes | Use `coho` CLI directly |
| Cursor | Yes | Use `coho` CLI directly |
| Claude Desktop | No | This MCP server |
### For AI Agents with Terminal Access (Claude Code, Cursor, etc.)
Using the Codehooks CLI directly is simpler and more flexible:
1. Install the CLI: `npm install -g codehooks`
2. Login: `coho login`
3. Get the AI prompt: `coho prompt`
4. Or reference the online docs: https://codehooks.io/llms.txt
The agent can then run `coho` commands directly in the terminal.
### For Claude Desktop (No Terminal Access)
Use this MCP server to give the AI access to Codehooks functionality. See the [Setup](#setup) section below.
## Available functionality
### Database & Collections
- Query and update collections (including metadata) with filters and sorting
- Create and manage collections
- Import/export data (JSON,JSONL,CSV)
- Add schemas and indexes, cap collections
### Code Deployment
- Deploy JavaScript serverless functions
### File Operations
- Upload files to cloud storage
- List and browse files
- Delete files
- Inspect file metadata
### Key-Value Store
- Store key-value pairs
- Retrieve one or many key-value pairs
- Delete key-value pairs
- Set time-to-live (TTL) for key-value pairs
### System Operations
- View application logs
- Access API documentation (local documentation for the MCP agent)
## Setup
### Get Codehooks Admin Token (keep it secret!)
```bash
coho login
coho add-admintoken
```
### Create MCP Server Script
Create a folder for your MCP server scripts:
```bash
mkdir ~/mcp-servers
cd ~/mcp-servers
```
**For macOS/Linux** - Create `codehooks.sh`:
```bash
#!/bin/bash
# Set PATH to include common Docker locations
export PATH="/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:$PATH"
exec docker run --rm -i \
--pull always \
-e CODEHOOKS_PROJECT_NAME=your_project_name \
-e CODEHOOKS_ADMIN_TOKEN=your_admin_token \
-e CODEHOOKS_SPACE=your_space_name \
ghcr.io/restdb/codehooks-mcp:latest
```
Make it executable:
```bash
chmod +x ~/mcp-servers/codehooks.sh
```
**For Windows** - Create `codehooks.bat`:
```batch
@echo off
docker run --rm -i ^
--pull always ^
-e CODEHOOKS_PROJECT_NAME=your_project_name ^
-e CODEHOOKS_ADMIN_TOKEN=your_admin_token ^
-e CODEHOOKS_SPACE=your_space_name ^
ghcr.io/restdb/codehooks-mcp:latest
```
Replace `your_project_name`, `your_admin_token`, and `your_space_name` with your actual values.
### Configure for Claude Desktop
Add to your `claude_desktop_config.json`:
**macOS/Linux:**
```json
{
"mcpServers": {
"codehooks": {
"command": "/Users/username/mcp-servers/codehooks.sh"
}
}
}
```
**Windows:**
```json
{
"mcpServers": {
"codehooks": {
"command": "C:\\Users\\username\\mcp-servers\\codehooks.bat"
}
}
}
```
### Configure for Cursor
Add to your `~/.cursor/mcp.json`:
**macOS/Linux:**
```json
{
"mcpServers": {
"codehooks": {
"command": "/Users/username/mcp-servers/codehooks.sh"
}
}
}
```
**Windows:**
```json
{
"mcpServers": {
"codehooks": {
"command": "C:\\Users\\username\\mcp-servers\\codehooks.bat"
}
}
}
```
Replace `username` with your actual username.
## Example Requests
- "Build a complete survey system: create a database, deploy an API to collect responses, and add search/analytics endpoints"
- "Set up a real-time inventory tracker: import my product CSV, create stock update webhooks, and build low-stock alerts"
- "Build a webhook processing pipeline: receive webhooks from multiple sources, transform and validate data, then trigger automated actions"
- "Build a content management system: create file upload endpoints, set up a metadata database, and deploy content delivery APIs"
- "Set up automated data backups: export my collections to JSON files, store them with timestamps, and create restoration endpoints"
## How These Examples Work
### Complete Survey System
**The AI agent would:**
1. **Create collections** (`surveys`, `responses`) for data storage
2. **Add schemas** for data validation and structure
3. **Deploy JavaScript endpoints** like `POST /surveys` and `GET /surveys/:id/analytics`
4. **Create indexes** on response fields for fast searching and analytics
### Real-time Inventory Tracker
**The AI agent would:**
1. **Import your CSV** to populate the `products` collection
2. **Deploy webhook handlers** for `POST /inventory/update` and `GET /inventory/low-stock`
3. **Set up key-value storage** for alert thresholds and settings
4. **Create indexes** on SKU and stock levels for real-time queries
### Webhook Processing Pipeline
**The AI agent would:**
1. **Deploy webhook receivers** like `POST /webhooks/stripe` and `POST /webhooks/github`
2. **Create collections** for `webhook_logs`, `processed_events`, and `failed_events`
3. **Set up data transformation** rules and validation schemas for each webhook source
4. **Use key-value store** for rate limiting and duplicate detection with TTL
5. **Deploy action triggers** that send emails, update databases, or call other APIs based on webhook data
### Content Management System
**The AI agent would:**
1. **Create collections** for `content`, `media`, and `users`
2. **Deploy file upload endpoints** with `POST /upload` and `GET /content/:id`
3. **Upload and manage static files** for content delivery
4. **Store metadata** linking files to content records with search indexes
### Automated Data Backups
**The AI agent would:**
1. **Export collections** to JSON format with timestamps
2. **Upload backup files** to cloud storage automatically
3. **Deploy restoration APIs** like `GET /backups` and `POST /restore/:backup-id`
4. **Store backup metadata** in key-value store for tracking and management
Each example demonstrates how multiple MCP tools work together to create complete, production-ready systems through natural conversation with your AI agent.
## Security Researchers
We thank the following individuals for responsible disclosure and helping improve the security of this project:
- [Liran Tal](https://lirantal.com) – Reported a command injection vulnerability in the `query_collection` tool (May 2025)
## License
This project is licensed under the MIT License.
