# NocoDB MCP Server

A standard FastMCP Model Context Protocol server for seamless NocoDB integration with Claude Code.

## 🎯 What This Is

This MCP server provides Claude Code users with direct access to NocoDB operations. Built using the standard FastMCP library with streamable-http transport for remote hosting. Perfect for Discord Heart Reactions workflow and other NocoDB automation projects.

## ✨ Features

- **Complete NocoDB API Integration** - All CRUD operations supported
- **Discord Heart Reactions Optimized** - Built specifically for the Discord workflow
- **Production Ready** - Health checks, rate limiting, graceful shutdown
- **Docker Ready** - Easy deployment with Docker or Coolify
- **Auto-deployment** - GitHub Actions for automated builds
- **Comprehensive Monitoring** - Built-in health checks and metrics

## 🚀 Quick Deployment

### Option 1: Coolify (Recommended)
1. **Create New Resource** → Docker Image
2. **Image**: `gordov1su4/mcp-server-nocodb:1.2.0`
3. **Port**: `3001`
4. **Environment Variables**:
   - `NOCODB_API_TOKEN=your_token`
   - `NOCODB_URL=https://nocodb.v1su4.com`
   - `PORT=3001`
5. **Health Check**: `/health` endpoint
6. Deploy and enjoy!

For detailed Coolify deployment instructions, see [COOLIFY_DEPLOYMENT_GUIDE.md](COOLIFY_DEPLOYMENT_GUIDE.md).

### Option 2: Docker
```bash
# Use pre-built image
docker run -p 3001:3001 \
  -e NOCODB_API_TOKEN=your_token \
  -e NOCODB_URL=https://nocodb.v1su4.com \
  gordov1su4/mcp-server-nocodb:1.2.0

# Or build locally
docker build -t mcp-server-nocodb:1.2.0 .
docker run -p 3001:3001 \
  -e NOCODB_API_TOKEN=your_token \
  -e NOCODB_URL=https://nocodb.v1su4.com \
  mcp-server-nocodb:1.2.0
```

### Option 3: Docker Compose
```bash
# Standard deployment
docker-compose up -d

# View logs
docker-compose logs -f mcp-server-nocodb
```

## 🔧 Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `NOCODB_API_TOKEN` | Yes | - | Your NocoDB API token (from Account Settings → Tokens) |
| `NOCODB_URL` | No | `https://nocodb.v1su4.com` | NocoDB instance URL |
| `PORT` | No | `3001` | Server port |
| `PYTHONUNBUFFERED` | No | `1` | Python output buffering |

**Note**: This server uses **NocoDB API v3** as the primary API (requires NocoDB 0.264.0+). Latest stable: 0.265.1. It automatically falls back to v2 if v3 is not available. API v3 provides embedded relations, unified record linking, and standardized responses.

## 📊 Available MCP Tools

**Note**: This server uses NocoDB API v2. In API v2, "projects" are called "bases", but tool names maintain backward compatibility.

### Connection & Management
- `nocodb_test_connection` - Test NocoDB connection and list bases (projects)
- `nocodb_list_projects` - List all bases (projects in API v2 terminology)
- `nocodb_list_tables` - List tables in a base (project_id parameter is base_id)

### Data Operations
- `nocodb_get_records` - Retrieve records with pagination
- `nocodb_create_record` - Create new records
- `nocodb_update_record` - Update existing records
- `nocodb_delete_record` - Delete records
- `nocodb_search_records` - Search with filters

### Specialized Tools
- `nocodb_create_discord_reactions_table` - Create Discord reactions table
- `nocodb_get_analytics` - Get Discord reactions analytics

## 🧪 Testing

### Health Check
```bash
curl https://mcp-nocodb.v1su4.com/
```

### Test Connection
```bash
curl -X POST https://mcp-nocodb.v1su4.com/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"health_check","arguments":{}},"id":1}'
```

## 📋 Claude Code Integration

1. **Update MCP Configuration**:
   ```json
   {
     "mcpServers": {
       "nocodb": {
         "transport": {
           "type": "streamable-http",
           "url": "https://mcp-nocodb.v1su4.com/"
         }
       }
     }
   }
   ```

2. **Restart Claude Code** and enjoy NocoDB tools!

### Option 2: Claude CLI (Recommended for newer versions)

1. **Add your MCP server**:
   ```bash
   claude mcp add --transport streamable-http nocodb https://mcp-nocodb.v1su4.com/
   ```

2. **Manage existing connections**:
   ```bash
   # List all connected servers
   claude mcp list
   
   # Remove old connections (if needed)
   claude mcp remove server-name
   ```

3. **Test the connection**:
   ```bash
   claude mcp test nocodb
   ```

## 🏗️ Architecture

```
Claude Code → Hosted FastMCP Server (SSE) → NocoDB API v3
```

- **FastMCP Server**: Standard MCP server with streamable-http transport
- **Server-Sent Events**: Real-time communication via SSE protocol
- **NocoDB API v3**: Primary API using `/api/v3/` endpoints (NocoDB 0.264.0+). Falls back to v2 if needed.

## 🔄 Native MCP vs Custom MCP

NocoDB now has **native MCP Server support** (0.265.0+) as documented in the [official MCP documentation](https://nocodb.com/docs/product-docs/mcp). 

### ⚠️ Important: Do You Still Need This Custom Server?

**You may not need this custom deployment if:**
- ✅ You only need standard CRUD operations (native MCP handles this)
- ✅ You're okay with one endpoint per base (native MCP is per-base)
- ✅ You want OAuth for web clients (native MCP supports this)

**Keep this custom server if you need:**
- ✅ **Table creation** (`nocodb_create_discord_reactions_table`)
- ✅ **Custom analytics** (`nocodb_get_analytics`)
- ✅ **Cross-base operations** (all bases in one server)
- ✅ **Custom workflows** (Python-based logic)

See [MIGRATION_TO_NATIVE_MCP.md](MIGRATION_TO_NATIVE_MCP.md) for a decision guide.

**This custom server provides:**
- ✅ Cross-base operations (all bases in one server)
- ✅ Custom tools (analytics, table creation)
- ✅ Works with any NocoDB version
- ✅ Single deployment for all bases

**Native MCP provides:**
- ✅ OAuth integration for web clients (Claude Web, ChatGPT)
- ✅ Base-specific access control
- ✅ Official NocoDB support
- ✅ No separate deployment needed

**Both can be used together** - Native for OAuth/web clients, custom for desktop/cross-base operations.

**Self-Hosted Setup:** For native MCP, use `https://nocodb.v1su4.com/mcp` instead of `https://app.nocodb.com/mcp`. See [SELF_HOSTED_NATIVE_MCP_SETUP.md](SELF_HOSTED_NATIVE_MCP_SETUP.md) for details.
- **Compatibility**: Works with NocoDB v2+ instances, compatible with n8n workflows

## 📚 Documentation

- **[Coolify Deployment Guide](COOLIFY_DEPLOYMENT_GUIDE.md)** - Detailed deployment instructions for Coolify
- **[NocoDB API Setup Guide](NOCODB_API_SETUP_GUIDE.md)** - NocoDB API configuration and setup
- **[Troubleshooting Guide](MCP_SERVER_TROUBLESHOOTING.md)** - Common issues and solutions
- **[Docker Configuration](Dockerfile)** - Container setup details

## 🔒 Security

- Rate limiting to prevent abuse
- API token authentication required
- HTTPS enforced
- Comprehensive logging
- Environment variable configuration

## 📈 Monitoring

- Real-time health checks
- Performance metrics
- Request logging
- Error tracking
- Resource usage monitoring

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## 📄 License

MIT License - feel free to use and modify as needed.

## 🆘 Support

For issues or questions:
1. Check the health endpoint
2. Review server logs
3. Test with the CLI tools
4. Check environment variables

---

**Built for Discord Heart Reactions workflow** 🎉