How to Integrate PicList with Typora or Obsidian: API and Configuration Guide

PicList exposes a local HTTP server on port 36677 that accepts image uploads via a REST API, enabling seamless integration with markdown editors like Typora and Obsidian through simple POST requests to the /upload endpoint.

PicList, an enhanced fork of PicGo maintained by Kuingsmile, includes a built-in HTTP server that transforms the desktop application into a local image hosting gateway. Understanding how to leverage this PicList Typora Obsidian integration allows you to automate image uploads directly from your favorite markdown editors without manual intervention. The server supports both multipart form data and JSON payloads, making it compatible with a wide range of external tools.

The Local Server Architecture

PicList runs a lightweight HTTP server locally to handle incoming upload requests from external applications.

Server Initialization and Default Port

The server initializes on 127.0.0.1 with a default port 36677. This configuration is defined in the core server file:

// src/main/server/index.ts#L15-L16
const host = config.host || '127.0.0.1'
const port = config.port || 36677

You can view the exact implementation in src/main/server/index.ts#L15-L16.

Request Handling with Multer

The server uses multer middleware to process multipart/form-data uploads. This allows editors to send images directly as file attachments rather than base64 strings:

// src/main/server/index.ts#L22-L35
const upload = multer({
  storage: multer.diskStorage({
    destination: (req, file, cb) => {
      cb(null, app.getPath('temp'))
    },
    filename: (req, file, cb) => {
      cb(null, Date.now() + '-' + file.originalname)
    }
  })
})

See the multipart configuration in src/main/server/index.ts#L22-L35.

The Upload API Endpoint

The primary integration point is the /upload endpoint, which receives images and returns public URLs after processing through your configured picbed (cloud storage).

Route Registration

The upload route is registered in the RPC router and forwards file lists to PicList’s uploader logic:

// src/main/events/rpc/routes/upload/index.ts#L25-L30
router.post('/upload', upload.array('list'), async (req, res) => {
  const list = req.files || req.body.list
  const result = await uploadManager.upload(list)
  res.json(result)
})

View the route handler in src/main/events/rpc/routes/upload/index.ts#L25-L30.

Supported Payload Formats

The endpoint accepts two formats:

1. Multipart/form-data: Send files as form fields named list (supports multiple files).
2. JSON payload: Send {"list": ["/absolute/path/to/image.png"]} for server-side file path resolution.

Configuring PicList for Editor Integration

Before connecting external editors, verify the server settings in PicList’s configuration interface.

Server Settings UI

The default port and host values are exposed in the settings page:

<!-- src/renderer/pages/PicGoSetting.vue#L1036 -->
<el-input v-model="form.port" placeholder="36677" />

Access the configuration UI at src/renderer/pages/PicGoSetting.vue#L1036. You can disable the server or change the port if 36677 conflicts with other services.

Configuration Paths

PicList stores server configuration using centralized path constants defined in [src/main/utils/configPaths.ts](https://github.com/kuingsmile/piclist/blob/dev/src/main/utils/configPaths.ts). This ensures consistent config file locations across operating systems.

Typora Integration Steps

Typora supports PicList natively in recent versions and via PicGo compatibility mode in older releases.

Typora 1.6.0 and Above

For version 1.6.0+, select PicList directly from the Image Settings dropdown:

"For Typora version >= 1.6.0, you can select PicList directly in the Image Settings." — README.md#L27-L31

Typora Below 1.6.0

For older versions:

1. Open Preferences → Image.
2. Set Image Upload to PicGo(app).
3. Point the uploader path to your PicList executable.

Reference the legacy instructions in README.md#L27-L31.

Obsidian Integration Steps

Obsidian requires the Image Auto Upload Plugin to communicate with PicList.

1. Install the plugin from the Obsidian community plugins.
2. Set Default Uploader to PicGo(app).
3. Configure the API endpoint to http://127.0.0.1:36677/upload.

The exact configuration is documented in README.md#L33-L36.

Once configured, any pasted or dragged images automatically upload through PicList and return public URLs.

Practical API Examples

Test your integration using these cURL commands before configuring editors.

Multipart Upload (Typora Default)

curl -X POST http://127.0.0.1:36677/upload \
  -F "list=@/Users/username/Desktop/screenshot.png"

JSON Upload (Path-Based)

curl -X POST http://127.0.0.1:36677/upload \
  -H "Content-Type: application/json" \
  -d '{"list":["/Users/username/Desktop/screenshot.png"]}'

Query Parameter for Specific Picbed

Override the default picbed by adding the picbed query parameter:

curl -X POST "http://127.0.0.1:36677/upload?picbed=aws-s3" \
  -F "list=@image.png"

Summary

• PicList runs an HTTP server on port 36677 by default, configurable via the settings UI ([src/main/server/index.ts](https://github.com/kuingsmile/piclist/blob/dev/src/main/server/index.ts)).
• The /upload endpoint accepts both multipart form data and JSON payloads ([src/main/events/rpc/routes/upload/index.ts](https://github.com/kuingsmile/piclist/blob/dev/src/main/events/rpc/routes/upload/index.ts)).
• Typora 1.6.0+ supports PicList natively, while older versions use PicGo(app) mode ([README.md](https://github.com/kuingsmile/piclist/blob/dev/README.md)).
• Obsidian integrates via the Image Auto Upload Plugin pointing to http://127.0.0.1:36677/upload.
• The server utilizes multer for file handling and supports custom picbed selection via query parameters.

Frequently Asked Questions

What port does PicList use for editor integrations?

PicList uses port 36677 by default. You can modify this in the PicList settings interface under the server configuration section (src/renderer/pages/PicGoSetting.vue#L1036). If this port is occupied, change it to any available port and update your editor settings accordingly.

Does PicList support both JSON and multipart uploads?

Yes. The upload endpoint handles multipart/form-data for direct file transfers (used by most editors) and JSON payloads containing file paths (useful for CLI workflows). Both methods return a JSON response containing the uploaded image URLs.

Can I use PicList with Typora versions older than 1.6.0?

Yes. For older Typora versions, configure the editor to use PicGo(app) mode instead of the native PicList option. Point the uploader executable path to the PicList binary location. This compatibility mode uses the same HTTP API on port 36677.

Is the PicList server available when running in Docker?

Yes. When running PicList in a Docker container, expose port 36677 using the -p 36677:36677 flag. External editors can then connect to the container's mapped port. Ensure the container has access to the image files or volumes mounted from the host system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}