# Codify MCP
**MCP server for custom automation tools using [Apify Agent](https://apify.com/cyberfly/apify-agent)**
> Part of [Project Codify](https://codify.codey.eu.org)
## Project Codify
Complete end-to-end browser automation pipeline running inside browser (or locally). Codify and replay browser actions as robust (deterministic) and reusable scripts.
From rapid prototyping and quick automation scripts to sophisticated deployments at scale.
- [Login](https://apify.com/cyberfly) - reusable authentication sessions - reusable secure login (TBD) ☑️
- [Agent](https://apify.com/cyberfly) - turn scripts into browser actions - code or text script (future) ✅
- [Coder](https://apify.com/cyberfly) - turn browser actions into scripts (TBD - currently integrated) ✅
- [Robot](https://apify.com/cyberfly) - automation engine for scalability (TBD - currently integrated) ✅
- [MCP](https://www.npmjs.com/package/codify-mcp) - automations become reusable tools you can reuse through AI ✅
More is on the way... Give it a [shot](https://codify.codey.eu.org) 🎬 or join the list to follow the project! 🔔
## What It Does
Model Context Protocol (MCP) server that lets AI assistants (e.g. Claude, Cursor, VS Code) execute browser automation tasks via Apify Agent. Tools are passed as clean JSON arguments — one per line. No manual setup or file creation.
## Usage
Run directly using `npx`:
```bash
npx codify-mcp {{JSON_MCP_TOOL_1}} {{JSON_MCP_TOOL_2}} {{JSON_MCP_TOOL_3}}...
```
Or install locally:
```bash
npm install -g codify-mcp
```
## Quick Start
### 1. Apify Token
Optional - you can also place the token inside the MCP server JSON later.
```bash
apify login
```
This saves your token to `~/.apify/auth.json`.
Alternatively, set the environment variable:
```bash
export APIFY_TOKEN="your_token_here"
```
### 2. Create a Tool
[Apify Coder](https://apify.com/cyberfly) can turn casual browser actions into reusable AI tools.
Currently, this feature is also integrated in [Apify Agent](https://apify.com/cyberfly/apify-agent)
Export a tool and append the result as a JSON string to the MCP server `args` field or ask your AI to do it for you.
```json
{
"name": "scrape_product",
"description": "Scrape product info from a page",
"inputSchema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Product page URL"
}
},
"required": ["url"]
},
"implementation": {
"type": "apify-actor",
"actorId": "cyberfly/apify-agent",
"script": "await page.goto(inputs.url); const title = await page.textContent('h1'); return {title};"
}
}
```
### 3. Run the Server
```bash
npx codify-mcp '{"name":"scrape_product","description":"...","inputSchema":{...},"implementation":{...}}'
```
Or with multiple tools:
```bash
npx codify-mcp \
'{"name":"tool1",...}' \
'{"name":"tool2",...}' \
'{"name":"tool3",...}'
```
### 4. Connect to Claude Desktop (or Cursor/VS Code)
Edit your Claude Desktop config:
**macOS/Linux:** `~/.config/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"apify-agent": {
"command": "npx",
"args": [
"codify-mcp",
"{\"name\":\"scrape_product\",\"description\":\"...\",\"inputSchema\":{...},\"implementation\":{...}}"
],
"env": {
"APIFY_TOKEN": "your_token_or_leave_empty_to_use_auth_file"
}
}
}
}
```
Restart Claude. Your tools are now available to the AI assistant.
## Tool Definition Reference
### Basic Structure
```javascript
{
// Required
"name": "tool_name", // alphanumeric + underscore/dash
"description": "What the tool does", // shown to AI
"inputSchema": {
"type": "object",
"properties": {
"paramName": {
"type": "string",
"description": "Parameter description"
}
},
"required": ["paramName"]
},
"implementation": {
"type": "apify-actor",
"actorId": "cyberfly/apify-agent", // actor to run
"script": "await page.goto(inputs.url); ..." // Playwright code
},
// Optional
"version": "1.0.0",
"metadata": { "custom": "fields" }
}
```
### Implementation Details
- **script**: Playwright automation code. Receives `inputs` object with user-provided parameters and `page` object for browser automation.
- **actorId**: Apify actor to execute. Defaults to `cyberfly/apify-agent`.
### Input Schema Examples
**Simple text input:**
```json
{
"url": {
"type": "string",
"description": "Website URL"
}
}
```
**Optional field:**
```json
{
"timeout": {
"type": "integer",
"description": "Timeout in seconds",
"default": 30
}
}
```
**Enum (dropdown):**
```json
{
"format": {
"type": "string",
"enum": ["json", "csv", "markdown"],
"description": "Output format"
}
}
```
## Usage Patterns
### Single Tool (Development)
```bash
npx codify-mcp '{"name":"test","description":"Test tool","inputSchema":{"type":"object","properties":{}},"implementation":{"type":"apify-actor","script":"console.log('hello')"}}'
```
### Multiple Tools (Production)
```bash
npx codify-mcp \
"$(cat tools/scraper.json)" \
"$(cat tools/logger.json)" \
"$(cat tools/analyzer.json)"
```
### With Environment Variable
```bash
APIFY_TOKEN="apk_..." npx codify-mcp '{"name":"...","description":"...","inputSchema":{},"implementation":{"type":"apify-actor","script":"..."}}'
```
### With npm link (Local Testing)
```bash
cd /path/to/codify-mcp
npm link
# Now use anywhere
codify-mcp '{"name":"...","description":"...","inputSchema":{},"implementation":{"type":"apify-actor","script":"..."}}'
```
## Authentication
Token resolution order:
1. **APIFY_TOKEN environment variable** (if set and not empty)
2. **~/.apify/auth.json** (from `apify login` CLI command)
3. **Error**: No token found, tool execution will fail with clear message
## Troubleshooting
### "No valid tools in arguments"
Ensure you're passing valid JSON strings as arguments:
```bash
# ✓ Correct
npx codify-mcp '{"name":"test","description":"Test","inputSchema":{"type":"object","properties":{}},"implementation":{"type":"apify-actor","script":"return {ok:true}"}}'
# ✗ Wrong (missing quotes around JSON)
npx codify-mcp {name:"test"...}
# ✗ Wrong (single quotes around JSON on Linux/Mac may need escaping)
npx codify-mcp '{name:"test"...}' # Use double quotes inside
```
### "Invalid or missing Apify token"
Ensure authentication is set up:
```bash
# Option 1: Login via CLI
apify login
# Option 2: Set environment variable
export APIFY_TOKEN="apk_your_token_here"
apify token
```
### "Tool execution failed"
Check your Playwright script syntax. The script must be valid JavaScript that:
- Has access to `inputs` (user-provided parameters)
- Has access to `page` (Playwright page object)
- Returns a value or object
```javascript
// ✓ Valid
await page.goto(inputs.url);
const title = await page.textContent('h1');
return { title };
// ✗ Invalid (missing await)
page.goto(inputs.url);
```
### Large Tool Sets (50+ tools)
If you have many tools, consider splitting into multiple MCP servers:
```json
{
"mcpServers": {
"apify-scraper": {
"command": "npx",
"args": ["codify-mcp", "...tool1...", "...tool2..."]
},
"apify-analyzer": {
"command": "npx",
"args": ["codify-mcp", "...tool3...", "...tool4..."]
}
}
}
```
## Development
### Running Locally
```bash
npm link
codify-mcp '{"name":"test",...}'
```
### Structure
```
lib/
index.js # Main entry: assembleWrapperCode(), start()
mcp/
resolver.js # Module path bootstrapping
auth.js # Token resolution
actor_caller.js # Apify actor execution
server_setup.js # MCP server + tool registration
bin/
start.js # Executable entry point (bin field in package.json)
```
## Key Design Principles
- **No files**: Tools passed entirely via argv; no config files or manual setup.
- **No base64**: Clean, readable command lines; no obfuscation.
- **Self-contained**: All dependencies bundled; works offline once installed.
- **Stateless**: Each invocation is independent; easy horizontal scaling.
- **Token from env/CLI**: Seamless auth experience; respects Apify ecosystem conventions.
## License
Apache-2.0
## Contributing
Issues and PRs welcome at [github.com/cybairfly/apify-agent](https://github.com/cybairfly/apify-agent)
