overskill-mcp

Build SaaS applications with AI agents using the Model Context Protocol.

This MCP server enables Claude Code, Cursor, and other MCP-compatible AI agents to create, deploy, and manage full-stack SaaS applications on Overskill.

Features

• Create Apps: Generate complete SaaS applications from natural language descriptions
• Manage Data: Create database entities and query/insert/update records
• Edit Files: View and modify source code files
• Deploy: Push changes to preview or production with 2-3 second deployments
• Secure: OAuth 2.0 authentication with scoped permissions

Installation

# Install globally
npm install -g overskill-mcp

# Or use directly with npx
npx overskill-mcp

Quick Start

1. Authenticate

npx overskill-mcp auth

This opens your browser to authenticate with Overskill. Your credentials are stored securely in ~/.overskill/credentials.json.

2. Configure Claude Code

Add to your MCP configuration (~/.config/claude/mcp_config.json or VS Code settings):

{
  "mcpServers": {
    "overskill": {
      "command": "npx",
      "args": ["overskill-mcp"]
    }
  }
}

3. Start Building!

Ask Claude Code to build your app:

"Create a task management app with due dates, priorities, and team collaboration"

Claude will use the Overskill tools to:

1. Generate the app (overskill-create-app)
2. Monitor progress (overskill-get-status)
3. Make refinements (overskill-write-file)
4. Deploy to production (overskill-deploy)

Available Tools

App Lifecycle

| Tool | Description | |------|-------------| | overskill-create-app | Create a new app from natural language | | overskill-get-app | Get app details, files, and entities | | overskill-list-apps | List all your apps | | overskill-deploy | Deploy to preview or production | | overskill-get-status | Check generation/deployment status |

Entity/Data Operations

| Tool | Description | |------|-------------| | overskill-create-entity | Create a database table | | overskill-query-data | Query records with filters | | overskill-insert-data | Insert new records | | overskill-update-data | Update existing records |

File Operations

| Tool | Description | |------|-------------| | overskill-view-file | View file contents | | overskill-write-file | Create or update files | | overskill-list-files | List files matching a pattern |

Commands

# Start MCP server (for Claude Code / Cursor)
npx overskill-mcp

# Authenticate with Overskill
npx overskill-mcp auth

# Check authentication status
npx overskill-mcp status

# Log out and clear credentials
npx overskill-mcp logout

# Show help
npx overskill-mcp help

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | OVERSKILL_API_URL | Overskill API base URL | https://overskill.com | | OVERSKILL_DEBUG | Enable debug logging | false |

Example Workflow

User: "Create a customer relationship management app"

Claude Code:
1. overskill-create-app
   → Creates app, returns preview URL

2. overskill-get-status (polls until complete)
   → Monitors generation progress

3. overskill-get-app
   → Gets file list and entities

4. overskill-view-file (src/App.tsx)
   → Reviews generated code

5. overskill-write-file (src/components/Dashboard.tsx)
   → Adds custom dashboard component

6. overskill-deploy (environment: production)
   → Deploys to https://my-crm.overskill.app

Total time: 30-90 seconds for a complete SaaS app!

Security

• OAuth 2.0: Industry-standard authentication with PKCE
• Scoped Permissions: Fine-grained access control
• Input Validation: All inputs validated with Zod schemas
• Rate Limiting: 100 requests per minute per user
• Audit Logging: All tool invocations logged for security

Rate Limits

• 100 requests per minute per user
• Burst capacity for initial requests
• Clear error messages when limits exceeded

Troubleshooting

"Not authenticated" error

Run the auth command:

npx overskill-mcp auth

"Rate limit exceeded" error

Wait a moment and try again. Rate limits reset every minute.

Connection issues

Check your internet connection and ensure https://overskill.com is accessible.

Debug mode

Enable verbose logging:

OVERSKILL_DEBUG=true npx overskill-mcp

Support

• Documentation: overskill.com/skill.md
• Issues: OverskillDev/overskill
• Support: overskill.com/support

Releasing

The package is built from source during publishing. Generated dist/ files are not checked into Git.

For the first release, merge the package into main, sign in with npm login, and run npm publish from this directory. Then configure npm trusted publishing with:

• Organization: OverskillDev
• Repository: overskill
• Workflow filename: publish-overskill-mcp.yml
• Allowed action: npm publish

For later releases:

1. Run npm version <major|minor|patch> --no-git-tag-version in this directory.
2. Merge that version change into main.
3. Publish a GitHub release from the merged commit with the tag mcp-server-v<version>.

The release workflow verifies the tag, runs the package smoke test, and publishes the public package to npm with a short-lived trusted publisher credential. It does not use an npm token stored in GitHub.

License

MIT