MCP 服务器

Poke Gate

An MCP server that lets your Poke AI assistant access your macOS machine, enabling shell commands, file operations, and screenshots through natural language.

README

Let your <a href="https://poke.com">Poke</a> AI assistant access your machine. A community project — not affiliated with Poke or The Interaction Company.

Run Poke Gate on your Mac, then message Poke from iMessage, Telegram, or SMS to run commands, read files, take screenshots, and more — all on your machine.

Install

Homebrew (recommended)

brew install f/tap/poke-gate

Install via npx

If you have Node.js installed, you can download and install the macOS app with a single command:

npx poke-gate download-macos

This downloads the latest DMG from GitHub Releases, installs the app to /Applications, and clears the quarantine flag automatically.

Don't have Node.js? Install it first:

# Option 1: Homebrew
brew install node

# Option 2: Download from https://nodejs.org

Manual download

Download the latest Poke.macOS.Gate.dmg from Releases, open it, and drag to Applications. Since the app is not notarized, you may need to run:

xattr -cr /Applications/Poke\ macOS\ Gate.app

CLI only (no macOS app needed)

If you just want to run poke-gate from the terminal without the menu bar app:

npx poke-gate

Setup

Open Poke Gate from your menu bar
The Setup View guides you through choosing an access mode and granting Accessibility permission
Sign in with Poke OAuth when prompted — a browser window opens automatically

The app connects automatically and shows a green dot when ready.

How it works

flowchart TD
    A["You message Poke\nfrom iMessage / Telegram / SMS"] --> B["Poke Agent"]
    B --> C["Agent calls MCP tool"]
    C --> D["MCP Tunnel (WebSocket)"]
    D --> E["Poke Gate on your Mac"]
    E --> F["Runs command / reads file / takes screenshot"]
    F --> D
    D --> B
    B --> A

Poke Gate runs a local MCP server and tunnels it to Poke's cloud. When you ask Poke something that needs your machine, the agent calls the tools, Poke Gate executes them locally, and the result flows back to your chat.

Tools

Tool	What it does
`run_command`	Execute any shell command (ls, git, brew, python, curl…)
`read_file`	Read a text file
`read_image`	Read an image file and return it as base64
`write_file`	Write content to a file
`list_directory`	List files and directories
`system_info`	OS, hostname, architecture, uptime, memory
`take_screenshot`	Capture the screen (requires Screen Recording permission)

Examples

From iMessage or Telegram, ask Poke:

"What's running on port 3000?"
"Show me the last 5 git commits in my project"
"How much disk space do I have left?"
"Read my ~/.zshrc and suggest improvements"
"Take a screenshot of my screen"
"Create a file called notes.txt on my Desktop"

macOS App

The native SwiftUI menu bar app manages everything:

First-run setup — guided onboarding to choose an access mode and grant Accessibility permission
Status — green dot when connected, yellow when connecting, red on error
Personalized — shows "Connected to your Poke, [name]"
Access mode — switch between Full, Limited, and Sandbox from Settings or the popover
Accessibility-first — prompts for Accessibility permission (needed for automation) with live status updates
Auto-start — connects on launch if signed in via OAuth
Auto-restart — reconnects automatically if the connection drops
Logs — view real-time tool calls with sandbox status
About — version pulled dynamically from the app bundle

The app runs in the menu bar only (no Dock icon). Quit is the only way to stop it.

Building from source

Requires macOS 15+ and Xcode 26+.

git clone https://github.com/f/poke-gate.git
cd poke-gate/clients/Poke\ macOS\ Gate
open Poke\ macOS\ Gate.xcodeproj

Hit Run in Xcode, or build from the command line:

./build.sh

CLI usage

The CLI requires Node.js 18 or later. If you don't have it, install via brew install node or download from nodejs.org.

Start the gate:

npx poke-gate

On first run, Poke OAuth opens in your browser. Add --verbose to see tool calls in real time:

npx poke-gate --verbose

Set the access mode with --mode:

npx poke-gate --mode limited
npx poke-gate --mode sandbox

Install or update the macOS app:

npx poke-gate download-macos

Config is stored at ~/.config/poke-gate/config.json.

Agents

Agents are scheduled scripts that run automatically in the background. They live in ~/.config/poke-gate/agents/ and follow a simple naming convention:

<name>.<interval>.js

File	Runs
`beeper.1h.js`	Every hour
`backup.2h.js`	Every 2 hours
`health.10m.js`	Every 10 minutes
`cleanup.30m.js`	Every 30 minutes

Intervals: Nm (minutes) or Nh (hours). Minimum is 10 minutes.

Install an agent

Download a community agent from the repository:

npx poke-gate agent get beeper

This downloads beeper.1h.js and .env.beeper to ~/.config/poke-gate/agents/. Edit the env file with your credentials and test it:

nano ~/.config/poke-gate/agents/.env.beeper
npx poke-gate run-agent beeper

Per-agent env files

Each agent can have a .env.<name> file for secrets:

~/.config/poke-gate/agents/.env.beeper

BEEPER_TOKEN=your_token_here

Variables are injected into the agent process automatically.

Agent frontmatter

Each agent file starts with a JSDoc-style frontmatter block:

/**
 * @agent beeper
 * @name Beeper Message Digest
 * @description Fetches messages from the last hour and sends a summary to Poke.
 * @interval 1h
 * @env BEEPER_TOKEN - Beeper Desktop local API token
 * @author f
 */

Creating your own agent

An agent is just a JS file that runs with Node.js. It has access to:

process.env — variables from .env.<name>
poke package — import { Poke, getToken } from "poke"
Any npm package installed globally or via npx

/**
 * @agent my-agent
 * @name My Custom Agent
 * @description Does something useful every 30 minutes.
 * @interval 30m
 */

import { Poke, getToken } from "poke";

const poke = new Poke({ apiKey: getToken() });
await poke.sendMessage("Hello from my agent!");

Save as ~/.config/poke-gate/agents/my-agent.30m.js and it runs automatically when poke-gate is connected.

Agents start running when poke-gate connects and run once immediately on startup.

Access modes

Poke Gate supports three access modes that control what your agent can do:

Mode	Description
Full (default)	All tools available with no approval required. The agent can run commands, write files, and take screenshots directly.
Limited	Read-only tools plus a curated set of safe commands (`ls`, `cat`, `grep`, `curl`, etc.). `write_file` and `take_screenshot` are disabled.
Sandbox	Broader command support than Limited, but writes are restricted to `~/Downloads` and `/tmp` via macOS `sandbox-exec`.

Set the mode via CLI flag, environment variable, or the macOS app Settings:

npx poke-gate --mode sandbox
# or
POKE_GATE_PERMISSION_MODE=limited npx poke-gate

Security

In full mode, Poke Gate grants full shell access to your Poke agent. This means:

Any command can be run with your user's permissions
Files can be read and written anywhere your user has access
Risky tools require approval in chat before execution
Only your Poke agent (authenticated via Poke OAuth) can reach the tunnel

Only run Poke Gate on machines and networks you trust. Use limited or sandbox mode if you want tighter restrictions.

Credits

License

MIT