Citizen Deployment MCP Server

Model Context Protocol (MCP) server for deploying applications to Citizen platform. Deploy from git or local files with intelligent error handling and automatic fixes.

Works with:

• ✅ Claude Desktop
• ✅ Claude Code (VS Code Extension)
• ✅ Cursor
• ✅ VS Code with MCP extension

Installation

npm install -g @citizenteam/mcp
# or
bun install -g @citizenteam/mcp

Quick Setup

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "citizen": {
      "command": "npx",
      "args": ["-y", "@citizenteam/mcp"]
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Claude Code (VS Code Extension)

1. Open VS Code settings (Cmd/Ctrl + ,)
2. Search for "MCP Servers"
3. Click "Edit in settings.json"
4. Add:

{
  "claude.mcpServers": {
    "citizen": {
      "command": "npx",
      "args": ["-y", "@citizenteam/mcp"]
    }
  }
}

Cursor

1. Open Cursor Settings → Features → MCP
2. Click "Add MCP Server"
3. Enter configuration:

{
  "citizen": {
    "command": "npx",
    "args": ["-y", "@citizenteam/mcp"]
  }
}

Or manually edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "citizen": {
      "command": "npx",
      "args": ["-y", "@citizenteam/mcp"]
    }
  }
}

VS Code (with MCP extension)

1. Install MCP extension for VS Code
2. Open settings.json (Cmd/Ctrl + Shift + P → "Preferences: Open Settings (JSON)")
3. Add:

{
  "mcp.servers": {
    "citizen": {
      "command": "npx",
      "args": ["-y", "@citizenteam/mcp"]
    }
  }
}

First Time Setup

1. Restart your IDE/Claude Desktop after adding the configuration
2. Use the authenticate tool to login with device flow
3. Follow the device authorization link in your browser
4. Once authorized, you can deploy apps!

Available Tools

Authentication

• authenticate - Login with device flow
• check_auth_status - Check auth status

App Management

• list_apps - List your apps (RBAC filtered)
• get_app_info - Get app details

Deployment

• deploy_from_git - Deploy from git repository
• deploy_from_local - Deploy from local directory
• get_deployment_status - Check deployment status and logs
• list_deployment_runs - List recent deployments

Available Resources

Deployment Instructions (citizen://instructions)

A comprehensive guide that helps LLMs understand:

• Complete deployment workflows (git and local)
• Error handling and debugging strategies
• How to fix common build errors (Python version, Node version, port binding, etc.)
• Best practices for monitoring deployments
• RBAC permission model
• Common nixpacks configurations
• Example conversations and use cases

Your AI assistant will automatically read this resource to understand how to properly use the deployment tools, monitor builds, and fix errors when they occur.

Example Usage

Basic Deployment

You: Deploy my app from github.com/user/repo.git

AI will:
1. Read the deployment instructions to understand the workflow
2. Check if you're authenticated
3. List your apps to see what's available
4. Deploy using deploy_from_git tool
5. Monitor the deployment with get_deployment_status
6. If errors occur, analyze logs and suggest fixes

Deployment with Error Handling

You: Deploy my Flask app from the current directory

AI will:
1. Deploy using deploy_from_local (creates tar.gz automatically)
2. Monitor build progress
3. If build fails (e.g., "Python 3.11 not found"):
   - Read the error from logs
   - Create/update nixpacks.toml with correct Python version
   - Redeploy automatically
4. Continue monitoring until successful

Interactive Debugging

You: My last deployment failed, can you help?

AI will:
1. List recent deployment runs
2. Get detailed logs for the failed run
3. Analyze the error (missing dependency, version mismatch, etc.)
4. Suggest and apply fixes
5. Redeploy with corrections

Features

• 🔐 Secure Device Authentication - OAuth-like device flow, no passwords needed
• 🚀 Git & Local Deployment - Deploy from GitHub or local files
• 🤖 Intelligent Error Fixing - AI analyzes logs and fixes build errors automatically
• 📊 Real-time Monitoring - Live deployment logs and status updates
• 🔒 RBAC Support - Role-based access control (viewer, member, admin, owner)
• 🏗️ Auto-detect Builders - Supports nixpacks and Dockerfile
• 🔄 Fast Iteration - Local deployment for quick fixes without git commits

Requirements

• Node.js 18+ or Bun
• Citizen platform account (sign up)
• One of: Claude Desktop, Claude Code, Cursor, or VS Code with MCP extension

Troubleshooting

Authentication Issues

• Make sure you've run the authenticate tool
• Check if your token has expired with check_auth_status
• Verify you're using the correct organization

Deployment Failures

• The AI will automatically analyze logs and suggest fixes
• Common issues: Python/Node version mismatches, missing dependencies, port binding
• Use deploy_from_local for faster iteration when fixing errors

Permission Denied

• Check your role with list_apps - you may not have access to that app
• Contact your organization admin to grant you member+ role

Links

• NPM Package
• Citizen Platform
• Model Context Protocol
• Report Issues

License

MIT © Citizen Team