# Quick Start Guide - Twenty CRM MCP Server
## Prerequisites
- Node.js 18+
- npm
- Docker (for containerized deployment)
- kubectl (for Kubernetes deployment)
- Twenty CRM account with API access
## 1. Initial Setup
```bash
# Clone the repository (if not already done)
# cd into the project directory
# Run initial setup - installs dependencies and creates .env file
make setup
# Edit .env file with your Twenty CRM API key
# Get your API key from: https://app.twenty.com/settings/developers
nano .env # or use your preferred editor
```
Update the `.env` file:
```bash
TWENTY_API_URL=https://api.twenty.com
TWENTY_API_KEY=your_actual_api_key_here
PORT=5008
```
## 2. Development
### Start Development Server
```bash
# Start the development server with auto-reload
make dev
```
The server will be available at:
- **Home Page**: http://localhost:5008
- **MCP Endpoint**: http://localhost:5008/mcp
- **Health Check**: http://localhost:5008/health
### Open MCP Inspector
```bash
# In a new terminal
make inspect
```
This opens the MCP Inspector at http://localhost:6274 for testing tools.
## 3. Testing
```bash
# Run all tests
make test
# Run tests with coverage
make test-coverage
# Run tests in watch mode
make test-watch
# Open test UI
make test-ui
```
## 4. Building
```bash
# Build the TypeScript project
make build
# Build and run all tasks (install, build, test)
make all
```
## 5. Docker Deployment
### Build and Run Locally
```bash
# Build Docker image
make docker-build
# Run Docker container (automatically builds if needed)
make docker-run
# View logs
make docker-logs
# Check health
make health
# Stop container
make docker-stop
```
### Docker Management
```bash
# Open shell in running container
make docker-shell
# Clean up Docker resources
make docker-clean
```
## 6. Kubernetes Deployment
### Local k3d Cluster
```bash
# Create k3d cluster (one-time setup)
make k3d-setup
# Build and import image to k3d
make k3d-import
# Create Kubernetes secret with API key
make k8s-secret
# Deploy to Kubernetes (does all above steps)
make deploy
```
### Kubernetes Management
```bash
# Check deployment status
make k8s-status
# View pod logs
make k8s-logs
# Open shell in pod
make k8s-shell
# Restart deployment
make k8s-restart
# Delete deployment
make k8s-delete
# Delete k3d cluster
make k3d-delete
```
## 7. Available MCP Tools
Once the server is running, you can use these tools:
### Person Management
- `create-person` - Create a new person
- `get-person` - Get person by ID
- `update-person` - Update person information
- `delete-person` - Delete a person
- `list-persons` - List all persons
### Company Management
- `create-company` - Create a new company
- `get-company` - Get company by ID
- `list-companies` - List all companies
### Opportunity Management
- `create-opportunity` - Create a new opportunity
- `get-opportunity` - Get opportunity by ID
- `list-opportunities` - List all opportunities
## 8. Testing Tools via Web Interface
1. Visit http://localhost:5008
2. Click **"Initialize & Get Session"** to create an MCP session
3. Use the provided curl commands to test each tool
4. Each command automatically includes your session ID
## 9. Common Commands
```bash
# Quick Reference
make help # Show all available commands
make info # Display project information
make dev # Start development server
make test # Run tests
make build # Build project
make docker-run # Run in Docker
make deploy # Deploy to Kubernetes
make clean # Clean build artifacts
make health # Check server health
```
## 10. Maintenance
```bash
# Update dependencies
make update
# Run security audit
make audit
# Fix security vulnerabilities
make audit-fix
# Clean all build artifacts
make clean
# Clean everything including node_modules
make clean-all
```
## 11. CI/CD Pipeline
```bash
# Run full CI pipeline (install, build, lint, test)
make ci
```
## Troubleshooting
### API Key Issues
```bash
# Verify environment is configured
make check-env
# If API key is invalid, update .env and restart
nano .env
make docker-stop
make docker-run
```
### Port Already in Use
```bash
# Stop any existing server
make docker-stop
# Or change port in .env
PORT=5009 make dev
```
### Docker Issues
```bash
# Clean up all Docker resources
make docker-clean
# Rebuild from scratch
make docker-build
make docker-run
```
### Kubernetes Issues
```bash
# Check status
make k8s-status
# View logs
make k8s-logs
# Restart deployment
make k8s-restart
# Delete and redeploy
make k8s-delete
make deploy
```
## Next Steps
1. **Explore the API**: Visit http://localhost:5008 to see the interactive interface
2. **Test Tools**: Use the MCP Inspector to test each tool
3. **Integrate**: Connect your AI agent to the MCP server
4. **Customize**: Add more Twenty CRM entities (Note, Task, etc.)
5. **Deploy**: Use `make deploy` to deploy to your Kubernetes cluster
## Getting Help
- Run `make help` to see all available commands
- Run `make info` to see system information
- Check logs with `make docker-logs` or `make k8s-logs`
- Review the main [README.md](README.md) for detailed documentation
## Example Workflow
```bash
# Day 1 - Setup
make setup
# Edit .env with your API key
make dev
# Test in browser at http://localhost:5008
# Day 2 - Development
make dev
# Make code changes
# Server auto-reloads
# Day 3 - Testing
make test
make test-coverage
# Day 4 - Deployment
make docker-build
make docker-run
make health
# Day 5 - Production
make deploy
make k8s-status
```
Enjoy using Twenty CRM MCP Server! 🚀
