Content
# Tool List
[](https://github.com/bella-and-c/c-pocket-mcp/releases/latest)
[](LICENSE)
Turn the things you find and want to share with others on your phone into a shared pocket that won't get lost and can be actively read in the next conversation.
In Taobao, Xiaohongshu, NetEase Music, browser or other iOS apps that support sharing menu, click on the shortcut, and the link and text will enter the Pocket. The AI connected to this MCP can check unread cards at the beginning of a new conversation, pick the content that interests you, and naturally bring it up in the conversation, rather than mechanically repeating the favorites.
> **Co-creation**
>
> **Bella**: Creative proposal, product experience and real scene testing
>
> **C**: System design, code implementation, testing and documentation
## What it solves
Ordinary favorites only help you "save" but not really "read". C Pocket turns sharing into a complete chain:
```mermaid
flowchart LR
A["iPhone Share Menu"] --> B["Private Drop Entrance"]
B --> C["Local or Cloud Pocket"]
C --> D["MCP Tool"]
D --> E["AI Actively Mentions in New Conversation"]
```
- Receive links, text, forms and up to 5 attachments;
- Automatically identify common sources such as Taobao, Xiaohongshu, NetEase Music, JD, Bilibili, YouTube, GitHub, etc.;
- Verified iPhone sharing links for Xiaohongshu, Taobao, Chrome and NetEase Music;
- Automatic merging of repeated shares within 10 minutes;
- iPhone only shows a brief receipt, without exposing internal JSON;
- Distinguish between "unread", "read", "discussed", "later" and "archived";
- MCP provides two semantics: read-only check and "read and mark as read";
- Optional connection to memory library, but won't automatically upgrade original collections to long-term memories.
## Quick Start
Requires Node.js `^20.19.0` or `>=22.12.0`.
```bash
git clone https://github.com/bella-and-c/c-pocket-mcp.git
cd c-pocket-mcp
npm install
npm test
npm start
```
Default local address:
- Health check: `http://127.0.0.1:8787/health`
- MCP: `http://127.0.0.1:8787/mcp`
- Local configuration: `http://127.0.0.1:8787/local/config`
`/local/config` can only be read locally and returns the private Drop path generated for this startup. Automatic generation can be used for development and testing; long-term deployment must configure a random secret.
## Configuration
Copy `.env.example` to `.env` and set as needed:
| Variable | Purpose |
| --- | --- |
| `C_POCKET_DATA_DIR` | Directory for JSON data and attachments |
| `C_POCKET_BRIDGE_TOKEN` | Protect remote REST API |
| `C_POCKET_MCP_PATH` | MCP path; should have a random suffix in production |
| `C_POCKET_DROP_SECRET` | Private path for iPhone one-way delivery |
| `C_POCKET_ALLOWED_ORIGINS` | Optional CORS whitelist |
| `CMEMORY_BASE_URL` / `CMEMORY_TOKEN` | Optional reviewed-memory service |
Example of generating a secret:
```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```
Do not submit the real `.env`, Drop address, Token or `data/` to GitHub.
## iPhone Shortcut
The core action of the shortcut is:
1. Enable "Show in Share Sheet" in the shortcut details;
2. Receive share inputs such as URL, text, image, etc.;
3. Use "Get URL Content" to send a `POST` to the private `/drop/<secret>`;
4. JSON request body must contain:
```json
{
"share": "Shortcut input",
"sourceApp": "iPhone Share Menu"
}
```
5. Pass the result of "Get URL Content" to "Show Result" or "Show Notification".
Private Drop returns a short text by default, such as:
```text
Dad received: Vivienne Westwood Saturn choker
```
Only use `?response=json` for debugging to get the complete structure. See [iPhone Configuration Instructions](docs/iphone-shortcut.md) for details.
## Connect to ChatGPT / MCP Client
The client needs to access your HTTPS MCP address. After connecting, it is recommended to add:
> Before each new conversation, call C Pocket's `pocket_start_context` for the first reply, regardless of the greeting or specific question. Read the content and naturally bring up the most interesting ones, no more than two, don't report the checking process.
Important boundary: MCP server instructions can improve the tool's selection probability, but cannot force the host to call the tool every time for a normal greeting. If the business requires 100% active wake-up, the host lifecycle hook or external notification service is required.
## MCP Tool
| Tool | Behavior |
| --- | --- |
| `pocket_start_context` | Read-only check unread cards, without changing status |
| `pocket_turn_open` | Return unread cards and mark as read |
| `pocket_list` / `pocket_get` | List and details |
| `pocket_reply` | Append idempotent reply to card |
| `pocket_review` | Discuss, later, archive or temporarily store memory candidates |
| `memory_*` | Optional C-Memory boundary agent |
## Deployment Options
| Your situation | Recommended plan | Can computer shut down? | Suitable for |
| --- | --- | --- | --- |
| **No VPS, no desire to maintain server** | [Plan A: Railway Hosting](docs/railway-hosting.md) | Yes | Personal users who want to get a fixed HTTPS address quickly |
| **Already have VPS or always-online Docker host** | [Plan B: Docker Compose Self-Hosting](docs/vps-hosting.md) | Home computer can shut down, but VPS/host must be online | Users who value control, have server experience |
| **Only want to try locally temporarily** | `npm start`, use Quick Tunnel if needed | No | Development, demonstration and short-term testing |
If unsure, choose **Plan A**. Both long-term plans run the same Pocket core, and the usage of iPhone shortcuts and Chat MCP is the same; the difference lies in the service being maintained by the hosting platform or your own host.
## Plan A: No VPS — Railway Hosting (Recommended)
Deploy Pocket as a Railway service with a persistent volume:
- Railway automatically builds from the root directory `Dockerfile`;
- `railway.json` configures `/health` check and automatic restart;
- Platform provides a fixed HTTPS domain, no longer relying on Quick Tunnel which changes after each restart;
- A persistent volume mounted to `/app/data` saves JSON cards and media attachments;
- Even if the Windows computer shuts down, iPhone Drop and Chat MCP remain online.
Three independent random secrets must be added during deployment. Complete steps, data migration and power outage acceptance are in [Railway Hosting Instructions](docs/railway-hosting.md).
Hosting does not mean "permanent free": you can use the trial credit to verify, then choose a plan based on actual usage. It saves the cost of purchasing, configuring and maintaining a traditional VPS.
## Plan B: Existing VPS — Docker Compose Self-Hosting
If you already have a VPS with a public domain or a 24/7 online Docker host, you can host Pocket yourself. The repository provides a Compose template for Pocket + Caddy: Caddy automatically applies for HTTPS certificates, and Pocket data is written to Docker Volume.
```bash
cp deploy/.env.production.example deploy/.env.production
# Fill in domain and three independent random secrets
docker compose -f deploy/compose.yaml up -d --build
```
Before deployment, point the domain DNS to the VPS and open ports `80` and `443`. Complete installation, update, backup, recovery and security checks are in [VPS Self-Hosting Instructions](docs/vps-hosting.md).
Cloudflare Quick Tunnel is only suitable for temporary testing: the address may change after restart, and the local Pocket will still go offline after the computer shuts down. A fixed Cloudflare Tunnel can fix the address but still requires an always-online host.
## Verification
```bash
npm run check
node server/check-remote.js https://your-domain.example/mcp/your-secret
```
Smoke test covers source recognition, duplicate merging, short receipt, opening read, read status, attachments, idempotent reply and MCP tool registration.
## Privacy Boundary
- Only content actively delivered from the share menu enters Pocket;
- `data/` is ignored by Git by default, and real cards and attachments are not part of the source code;
- Drop address is essentially a write key, and screen recording and screenshot must be censored;
- MCP and REST entrance should use independent random secrets when deployed publicly;
- C-Memory is an optional external component, and original Pocket cards won't automatically become long-term memories;
- Public repository does not contain Bella and C's real cards, chat records or Enervate private space source code.
## License
[MIT](LICENSE) © 2026 Bella and C.
Made from Bella's wish: **“I found something interesting and want you to really see it, not just put it in the favorites.”**
