@voidgram/mcp-server

What this is

This package is the thin bridge between an LLM host and a running VoidGram desktop app. Every tool call maps to one or more VoidGram REST endpoints (/api/v1/...), authenticated with a personal API key you generate in VoidGram's Settings UI.

When you install this MCP server into Claude, prompts like these start working:

• "Schedule 20 posts from ~/content/march, one every day at 9am PT."
• "Show me my last 10 failed posts and explain why each one failed."
• "Upload these three photos as a carousel with the caption I drafted in my notes."
• "What's on my VoidGram schedule for next week?"

The LLM picks the right tool(s), calls them, and the results flow back into your conversation. All the heavy lifting — OAuth, Private API, ngrok tunneling, Cloudflare Worker scheduling — stays inside VoidGram. The MCP server only speaks the REST API.

Installation

Prerequisites

• VoidGram desktop app installed and running (v3.3.0 or later — the /api/v1 stable contract ships with that release).
• An API key. Open VoidGram, go to Settings → API Keys, click Generate, and copy the key once (it's never shown again).
• Node.js 20 or later for running the MCP server.

Claude Code

claude mcp add voidgram --scope user -- npx -y @voidgram/mcp-server

Then set your API key in the MCP server config. Edit the entry in ~/.claude/mcp_settings.json (or wherever your host stores them) to include the env:

{
  "mcpServers": {
    "voidgram": {
      "command": "npx",
      "args": ["-y", "@voidgram/mcp-server"],
      "env": {
        "VOIDGRAM_API_KEY": "vg_live_...your key here...",
        "VOIDGRAM_URL": "http://localhost:3001"
      }
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json:

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

Add under mcpServers:

{
  "mcpServers": {
    "voidgram": {
      "command": "npx",
      "args": ["-y", "@voidgram/mcp-server"],
      "env": {
        "VOIDGRAM_API_KEY": "vg_live_...your key here...",
        "VOIDGRAM_URL": "http://localhost:3001"
      }
    }
  }
}

Restart Claude Desktop. You should see a hammer icon indicating VoidGram tools are available.

Happy, Cursor, other MCP hosts

Any MCP host that supports stdio-transport servers works. Invoke npx -y @voidgram/mcp-server with VOIDGRAM_API_KEY and optional VOIDGRAM_URL in the environment.

Required environment variables

Example prompts

Paste any of these into a Claude chat once the server is wired up:

• List my Instagram accounts connected to VoidGram.
• Upload ~/Pictures/sunset.jpg and draft a post for my @your_account account with the caption "golden hour #nofilter".
• Schedule that draft for tomorrow at 9am Pacific.
• Show me everything scheduled for the next 7 days.
• Cancel the scheduled post with id <uuid>.
• What are my last 10 failed posts, and what went wrong with each?
• How many story reposts did my @your_account do this week?

Tool reference

The LLM can also ask the MCP server to list tools at runtime — you don't need to memorise any of this.

Rate limit awareness

Instagram permits roughly 25 publishes per 24h per account (some accounts 50). If you're bulk-scheduling via the LLM, ask it to stagger posts by at least 20 minutes. The MCP server will surface a 429 with code: RATE_LIMITED and a retryAfter field if you hit the wall, which the LLM will then back off on.

Troubleshooting

VOIDGRAM_URL not reachable / NETWORK_ERROR / TIMEOUT

• Is the VoidGram desktop app running? Launch it, wait for the dashboard to load.
• Is VOIDGRAM_URL pointing at the right host:port? Default is http://localhost:3001. If you changed the VoidGram PORT env var, match it here.
• On Windows, if a firewall rule is blocking Node from making outbound HTTP to localhost, allow it.

AUTH_REQUIRED / AUTH_INVALID_KEY

• VOIDGRAM_API_KEY is not set, or the key was revoked/rotated.
• Go to VoidGram → Settings → API Keys, generate a new key, paste it into your MCP host's config env block, then restart the host (Claude Desktop must be fully quit and reopened — not just the window closed).

COOKIE_AUTH_REQUIRED

• You tried to create or revoke an API key via MCP. That's not allowed — key management requires the desktop UI session cookie. Generate/revoke keys in VoidGram's Settings page.

PRIVATE_API_REQUIRED

• You tried to schedule a story with @mention stickers but haven't configured Private API credentials for that account. Open VoidGram → Settings → Private API and sign in once.

Rate-limit / 429 errors

• You're publishing too fast. Instagram caps ~25/24h per account. Space posts further apart or reduce the batch size.

Tools don't show up in Claude

• Check stderr logs from the server. In Claude Desktop, the log lives at ~/Library/Logs/Claude/mcp-server-voidgram.log (macOS) or %APPDATA%\Claude\logs\mcp-server-voidgram.log (Windows).
• Verify the command in your host config resolves: open a terminal, run npx -y @voidgram/mcp-server. You should see [voidgram-mcp] starting v3.3.0 ... on stderr. Ctrl-C to exit.

Security notes

• API keys are bearer tokens. Anyone holding the key can act on your VoidGram account via the API. Treat them like passwords.
• Revoke keys you're not using in Settings → API Keys. The server stores only a SHA-256 hash, so keys can be rotated without re-encrypting the database.
• The MCP server itself stores nothing — it's stateless. Your key lives in the MCP host's config.
• Local-only by default. The server only reaches out to whatever VOIDGRAM_URL points at, and won't phone home.