AI assistants (MCP)

AI apps such as Claude, Claude Code, Cursor and Codex can talk to other apps through MCP, the Model Context Protocol. Goblin includes an MCP server, so you can ask your assistant things like "why is my fan so loud?", "what used the battery this afternoon?" or "which dev servers are running?" and it answers from Goblin's readings.

Most of what Goblin offers an assistant only reads. Some things change something: starting and stopping Keep Awake, adding or pinning clipboard items, and extracting or creating archives. Looking at your screen is a separate permission, too. Keep Awake, the clipboard, archives and the screen each have a switch of their own, off until you turn it on.

Turn it on#

Everything is on the AI Assistants card at the bottom of Settings›Projects. (Some of Goblin's messages call it "Settings › AI Assistants"; there's no pane by that name. It's this card.)

1. Right-click Goblin's menu bar item and choose Settings… (⌘,).
2. Click Projects in the sidebar and scroll to the AI Assistants card at the bottom.
3. Switch on Let AI assistants ask about this Mac.
4. Add Goblin to your AI app; see the next section.

Then ask the assistant something about your Mac, such as "What's slowing my Mac down right now?". It answers using Goblin's tools; most AI apps show a line such as get_vitals while they work.

Goblin checks this switch on every question, so turning it on or off takes effect at once, with no need to restart your AI app.

What leaves your Mac: the answers include app names, dev servers and network connections (and, once you allow it, clipboard items), and your AI app sends them to whichever AI service it uses. Goblin itself doesn't send anything anywhere; it only answers the app that asked.

Add Goblin to your AI app#

1. In Settings›Projects, scroll to the AI Assistants card.
2. Find your AI app in the list under the switches. The card lists the ones it finds on your Mac.
3. Click Add beside it. The status changes to Added.
4. Quit your AI app and open it again so it picks up the change.
5. Make sure Let AI assistants ask about this Mac is on.

Adding doesn't switch that on for you. If the card says "No supported AI app was found. Use the command or settings below.", set it up by hand (next section). The buttons mean:

After you click Add, restart the AI app so it picks up the change. Adding Goblin also installs the goblin command if it isn't there yet, because that's what the AI app runs. It doesn't turn on the switch above; do that too.

When Goblin edits an app's settings file, it changes only the goblin entry and keeps everything else, comments included. The first time, it saves a copy of the original next to it, ending in .goblin-backup.

If no supported app is found, the card says "No supported AI app was found. Use the command or settings below."

Setting it up by hand#

The card's own Add button does all of this for you. Set it up by hand if you use another app, or if the card can't edit the settings file.

Use the full path to the command, with your own user name in place of you. Many apps start the command directly rather than through a shell, and may not read ~ as your home folder. To find your full path, type this in Terminal:

echo ~/.local/bin/goblin

This prints something like /Users/you/.local/bin/goblin. Use what it prints. The card's own copy buttons hold the same text for Claude Code and for other apps. Setting it up by hand needs the goblin command installed.

Claude (desktop app)#

1. Open ~/Library/Application Support/Claude/claude_desktop_config.json in a text editor.
2. Add this, then save. If the file already has an mcpServers section, add only the goblin entry inside it.
3. Quit and reopen Claude.

{
  "mcpServers": {
    "goblin": {
      "command": "/Users/you/.local/bin/goblin",
      "args": ["mcp"]
    }
  }
}

Claude now lists Goblin's tools. Ask it "What's my Mac's CPU temperature?" to try it.

Claude Code#

Run this in Terminal (here the shell expands ~ for you):

claude mcp add --scope user goblin -- ~/.local/bin/goblin mcp

This adds Goblin to Claude Code and prints a line saying it was added. --scope user makes Goblin available in every project. To check, run claude mcp list. To remove it:

claude mcp remove --scope user goblin

This is the same command the card's Add button runs; if Goblin can't find Claude Code's claude command, it shows an error and asks you to run it yourself.

Cursor#

Add the same mcpServers entry as for Claude (above) to ~/.cursor/mcp.json, save, then quit and reopen Cursor.

Codex#

Add this table to ~/.codex/config.toml, save, then quit and reopen Codex:

[mcp_servers.goblin]
command = "/Users/you/.local/bin/goblin"
args = ["mcp"]

Other apps#

Most MCP apps take the same mcpServers JSON as Claude. The server is the command goblin mcp, and it talks over standard input and output. If you run goblin mcp in Terminal yourself, it waits for messages from an AI app; press ⌃C to stop it.

What an assistant can ask#

There are 34 tools. Each one says what it does, and AI apps show its name when they use it.

Right now#

These read the Mac directly, so they work even when the Goblin app isn't open.

Over time#

These read the 30-day history the Goblin app records while it runs. Each takes a period such as 1h, 24h, 7d or 30d, or a start and end time. If Goblin has never run, there's no history yet.

Network and firewall#

Keep Awake#

Let an assistant start and stop Keep Awake#

1. Open Settings›Keep Awake and scroll to AI Assistants.
2. Switch on Let AI assistants start and stop sessions.
3. Ask the assistant: "Keep my Mac awake for 2 hours". It starts a session, which appears in the Keep Awake card.

Starting and stopping need that second switch: Let AI assistants start and stop sessions in Settings › Keep Awake › AI Assistants. It's off by default. Until you turn it on, the assistant is told it isn't allowed, and can still ask whether a session is running. Goblin needs to be running or able to start, because these tools work through goblin://awake links.

Clipboard#

These let an assistant search and read your clipboard history and pinboards, save text to it, and pin items.

Let an assistant use the clipboard#

1. Open Settings›Clipboard and find the MCP & AI tools section.
2. Switch on Enable MCP.
3. Ask the assistant: "Find the link I copied from Safari yesterday".

They need a second switch: Enable MCP in Settings › Clipboard › MCP & AI tools, off by default. It's a setting for each Mac and never syncs. Until you turn it on, the assistant is told that clipboard access is off and asked to have you turn it on.

An assistant never gets passwords and other secrets Goblin detected, anything in the clipboard Trash, or anything in a locked pinboard, and it can't add to or pin into a locked pinboard. Like the other tools, these read Goblin's files directly, so they work even when the Goblin app isn't open.

Archives#

These work on any archive format Goblin opens; see Archives. Paths must be full paths. If an archive needs a password, the tool says so and the assistant asks you for it.

Let an assistant make and unpack archives#

1. Open Settings›Projects and scroll to the AI Assistants card.
2. Switch on Let AI assistants make and unpack archives.

Extracting and compressing need this switch. Until you turn it on, the assistant is told it isn't allowed, and can still list and check archives.

Your screen#

take_screenshot and read_screen_text need Let AI assistants see the screen in Capture's menu bar settings; see Automating capture. It's off by default. They ask the running Goblin to look, so Goblin must be running and have the Screen Recording permission, and they stop with a message if Goblin doesn't answer within 30 seconds. What's on your screen is the most private thing Goblin can show an AI. Your AI app should ask you before it calls these two.

If it doesn't work#

• The assistant says access is off. Turn on Let AI assistants ask about this Mac in Settings › Projects.
• The assistant says clipboard access is off. Turn on Enable MCP in Settings › Clipboard as well. Both switches have to be on.
• The app doesn't list Goblin's tools. Restart the AI app after adding Goblin. If you set it up by hand, check the command is the full path, not one starting with ~.
• History tools say there's no history. History builds up while the Goblin app runs. Open Goblin and leave it in the menu bar.
• Connection tools say the extension isn't reachable. They need the firewall turned on.