sublime_mcp_server

MCPServer

MCPServer is a Sublime Text package that exposes MCP tools over local HTTP from inside Sublime's Python runtime.

Today it ships with MCP tools for unsaved buffers:

• list_open_buffers
• read_buffer
• close_buffer

Use Cases

• Read temporary scratch notes or prompts directly from open unsaved tabs.
• Summarize or refine a draft in an AI client, then send the result to another MCP such as Notion.
• Clean up working tabs by closing consumed scratch buffers via close_buffer.
• Build lightweight editor automations without saving throwaway notes to disk.

The architecture is fully in-process. By default it starts:

• Sublime bridge on 127.0.0.1:6123
• MCP endpoint on 127.0.0.1:6124/mcp

No separate Node or TypeScript MCP server is required.

Requirements

• Sublime Text 4 build 4171 or newer
• Python 3.8 compatibility for the plugin package
• Python 3.11+ if you want to run the repo tests locally
• A local MCP client that can talk to a streamable HTTP MCP endpoint

Project Layout

• sublime_mcp_server/: bridge logic and in-process MCP HTTP server
• sublime_mcp_server_plugin.py: Sublime Text plugin entrypoint
• messages.json and messages/*.txt: Package Control install and upgrade messages
• python_tests/: pytest coverage for bridge and MCP behavior

Install The Sublime Plugin

For normal usage, install the packaged artifact into Sublime's Installed Packages folder.

On macOS:

mkdir -p "$HOME/Library/Application Support/Sublime Text/Installed Packages"
cp dist/MCPServer.sublime-package \
  "$HOME/Library/Application Support/Sublime Text/Installed Packages/MCPServer.sublime-package"

If you previously installed an unpacked development copy, remove it first so Sublime does not load the package twice:

rm -rf "$HOME/Library/Application Support/Sublime Text/Packages/MCPServer"

Restart Sublime Text after copying the files.

The packaged release includes the repository's tracked .python-version file at the package root so Sublime can select the correct Python runtime when loading the archive.

For local development, you can still use an unpacked checkout under Packages/MCPServer, but that is now a development-only workflow instead of the recommended installation method.

Port Configuration

The package reads its host and port configuration from MCPServer.sublime-settings.

Default values:

{
  "bridge_host": "127.0.0.1",
  "bridge_port": 6123,
  "mcp_host": "127.0.0.1",
  "mcp_port": 6124
}

To override them in Sublime Text:

1. Open the command palette.
2. Run Preferences: MCPServer Settings.
3. Put your overrides in the right-hand user settings pane.
4. Restart Sublime Text.

Example:

{
  "bridge_port": 7001,
  "mcp_port": 7002
}

The bridge and MCP ports must be different when using the same host.

Package And Release

There are two common release paths for Sublime Text packages:

• Package Control default channel: publish this repo on GitHub, create a semantic version tag such as 0.2.5, and submit the repository to Package Control once. After approval, future semver tags are how users receive updates.
• Custom distribution: build a .sublime-package archive and host your own packages.json channel if you do not want to use Package Control's default channel.

This repo now includes release-facing metadata:

• central package display name, MCP server name, version, and description in sublime_mcp_server/__init__.py
• Package Control install and upgrade messages in messages.json
• release notes for 0.2.5 in messages/0.2.5.txt

Suggested release checklist:

1. Update the version in pyproject.toml and sublime_mcp_server/__init__.py.
2. Add a matching upgrade note under messages/.
3. Build a .sublime-package artifact from the repo root:

python3 scripts/build_release.py

1. Run pytest and python3 -m py_compile sublime_mcp_server_plugin.py sublime_mcp_server/*.py.
2. Commit the release changes.
3. Create and push a semver tag such as 0.2.5.
4. If this is the first public release, submit the GitHub repository URL to Package Control.

For manual installs, use the generated dist/MCPServer.sublime-package file. The stable filename keeps the package name clean in Sublime, and the builder injects package-metadata.json so the description and version are visible in package UIs.

Verify The Plugin Is Running

Once Sublime restarts, the plugin should start two localhost services:

• GET http://127.0.0.1:6123/buffers
• POST http://127.0.0.1:6124/mcp

Check the bridge:

curl -sf http://127.0.0.1:6123/buffers | python3 -m json.tool

Check the MCP endpoint:

curl -sf \
  -X POST http://127.0.0.1:6124/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1.0.0"}}}' \
  | python3 -m json.tool

You should see serverInfo.name set to sublime_mcp_server.

If you changed the ports in settings, use those values instead of 6123 and 6124.

MCP Client Setup

This project serves MCP over HTTP from inside Sublime, so your MCP client only needs to connect to the plugin's endpoint.

Recommended MCP client configuration:

{
  "mcpServers": {
    "sublime_mcp_server": {
      "type": "http",
      "url": "http://127.0.0.1:6124/mcp"
    }
  }
}

Available Tools

list_open_buffers

Lists unsaved open Sublime buffers. Each buffer descriptor includes:

• buffer_id
• title
• window_id
• is_dirty
• syntax
• preview

read_buffer

Reads the current live text and metadata for one unsaved Sublime buffer.

Input:

{
  "buffer_id": "38"
}

close_buffer

Force-closes an unsaved Sublime buffer and discards its current contents.

Input:

{
  "buffer_id": "38"
}

Manual End-To-End Check

1. Open Sublime Text.
2. Create one or more new unsaved tabs.
3. Add some test text.
4. Verify the buffer list:

curl -sf http://127.0.0.1:6123/buffers | python3 -m json.tool

1. Use an MCP client or direct JSON-RPC request to list tools and read a buffer.

Direct JSON-RPC example:

curl -sf \
  -X POST http://127.0.0.1:6124/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | python3 -m json.tool

curl -sf \
  -X POST http://127.0.0.1:6124/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_buffer","arguments":{"buffer_id":"38"}}}' \
  | python3 -m json.tool

curl -sf \
  -X POST http://127.0.0.1:6124/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"close_buffer","arguments":{"buffer_id":"38"}}}' \
  | python3 -m json.tool

Development

Run tests:

pytest

Check syntax:

python3 -m py_compile sublime_mcp_server_plugin.py sublime_mcp_server/*.py