Skip to main content

Troubleshooting

Start with the shortest path that proves where the failure is: Glyphs, local endpoint, or MCP client configuration.

Quick checks​

  1. Relaunch Glyphs.

  2. Choose Edit -> Start Glyphs MCP Server.

  3. Open Edit -> Glyphs MCP Server Status... and confirm it is running.

  4. Confirm the endpoint is exactly:

    http://127.0.0.1:9680/mcp/

  5. Check that port 9680 is listening:

    lsof -iTCP:9680 -sTCP:LISTEN

  6. Check the local endpoint:

    curl -H 'Accept: application/json' http://127.0.0.1:9680/mcp/

No Glyphs menu items​

Expected menu items under Edit:

  • Start Glyphs MCP Server
  • Glyphs MCP Server Status...

Common causes:

  • The plug-in was not installed in the Glyphs plug-ins folder.
  • Glyphs has not been restarted since installation.

Fix:

  1. Quit Glyphs.

  2. Confirm Glyphs MCP.glyphsPlugin exists in:

    ~/Library/Application Support/Glyphs 3/Plugins/

  3. Rerun python3 install.py.

  4. Reopen Glyphs.

Client cannot connect​

Startup order often matters:

  1. Launch Glyphs.
  2. Start the MCP server.
  3. Launch or reload the client.

Then reconnect to:

http://127.0.0.1:9680/mcp/

If you changed the tool profile, restart the server and reload the client so it fetches the current tools/list.

Browser works but client does not​

A browser request can return discovery JSON, but MCP clients need a correct Streamable HTTP configuration. Confirm the client is using the endpoint above and not a shortened, redirected, or browser-only URL.

For client-specific setup, see Connect a client.

Python unsupported​

The installer supports Python 3.11-3.13.

Check your Python:

python3 --version

If you are on an unsupported version, install Python 3.12 from python.org and rerun the installer.

Missing dependencies​

If the plug-in starts but tool calls fail with ImportError or ModuleNotFoundError, dependencies may not be installed where Glyphs can load them.

Common location:

~/Library/Application Support/Glyphs 3/Scripts/site-packages

Advanced helper scripts from the repo root:

src/glyphs-mcp/scripts/install_deps_glyphs_python.sh
src/glyphs-mcp/scripts/install_deps_external_python.sh

Restart Glyphs after installing dependencies.

Port in use​

If another process is already bound to 127.0.0.1:9680, the server may fail to start.

lsof -iTCP:9680 -sTCP:LISTEN

Quit the other process or restart Glyphs.

Diagnostic prompt​

Paste this into your AI client:

Help me debug my Glyphs MCP connection.

1. Try to call list_open_fonts.
2. Tell me which endpoint you used.
3. If you see an error, quote it verbatim.
4. Based on the error, tell me the next 2-3 steps to try.