Content
# MCP-Server-Inbox
MCP service integrates with the [inBox 笔记](https://doc.gudong.site/inbox/) API to enable the creation of notes in a conversational format from any MCP client.
## Features
- Integrates with inBox 笔记 API
- Provides MCP service discovery interface
- Supports note creation via MCP client
- Supports setting note title (optional)
- Supports Inspector debugging tool
## Prerequisites
- Node.js 18+
- inBox 笔记 API (PRO features)
- Client that supports MCP protocol (e.g., Cursor AI)
## Installation and Usage
### Method 1: Run with npx
```bash
# Run the service
npx mcp-server-inbox --inbox_user_token=https://inbox.gudong.site/api/inbox/your_token_here
# Use environment variable
INBOX_USER_TOKEN=https://inbox.gudong.site/api/inbox/your_token_here npx mcp-server-inbox
```
### Method 2: Local Build
1. Clone the repository
```bash
git clone https://github.com/maoruibin/mcp-server-inbox.git
cd mcp-server-inbox
```
2. Install dependencies
```bash
npm install
```
3. Build the project
```bash
npm run build
```
4. Run the service
```bash
# Run the service
node build/index.js --inbox_user_token=https://inbox.gudong.site/api/inbox/your_token_here
# Use environment variable
INBOX_USER_TOKEN=https://inbox.gudong.site/api/inbox/your_token_here node build/index.js
```
## Debugging and Development
### Using Inspector
The project includes the MCP Inspector tool, which can help debug and monitor the service's running status:
```bash
npm run inspector
```
After running, you can access `http://localhost:5173` in your browser to view the service's running status and debugging information.
## Configuration in MCP Client
### Cursor AI
1. Open the MCP service configuration file for Cursor (usually located at `~/.cursor/mcp.json`)
2. Add the configuration for mcp-server-inbox:
```json
{
"mcpServers": {
"mcp-server-inbox": {
"command": "npx",
"args": [
"mcp-server-inbox"
],
"env": {
"INBOX_USER_TOKEN": "your api path"
}
}
}
}
```
### Other MCP Clients
Please refer to the configuration documentation for the respective MCP clients to add similar configuration information.
## Usage Examples
In clients that support MCP, you can use natural language to converse with AI to create notes:
- "Record: I learned about MCP development today"
- "Help me take a note, titled 'TypeScript Learning': Advanced types in TypeScript include Partial, Required, Pick, etc."
- "Write to inBox: I need to complete the project documentation tomorrow"
## API Description
### write_note
- Description: Write note content to inBox
- Parameters:
- title: Note title (optional)
- content: Note content (Markdown format), up to 3000 characters
- Returns:
- Success: Returns an object containing success information
- Failure: Throws the corresponding error message
### inBox API Description
This project relies on the inBox API service, detailed as follows:
#### Interface Information
- **Endpoint**: `https://app.gudong.site/api/inbox/${userToken}`
- **Request Method**: `POST`
- **Content-Type**: `application/json`
- **Request Rate**: Up to 50 requests per day
#### Request Parameters
| Parameter | Type | Required | Description |
|-----------|----------|----------|----------------------------|
| title | String | No | Note title |
| content | String | Yes | Note content, up to 3000 characters |
#### Usage Examples
1. Create a regular note:
```bash
npx mcp-server-inbox --inbox_user_token=https://inbox.gudong.site/api/inbox/your_token_here
```
2. Create a note with a title:
```bash
# Specify the title in the conversation
"Help me take a note, titled 'TypeScript Learning': Advanced types in TypeScript include Partial, Required, Pick, etc."
```
#### Response Format
```json
{
"code": 0,
"msg": "Submitted, please check inBox for the note"
}
```
> Note: A code of 0 indicates a successful request; any non-zero status indicates failure.
#### Image Support
The inBox API supports parsing Markdown format image tags. You can add Markdown formatted image links in the note content, for example:
```markdown
The weather is nice today, 
```
> Note: The API does not support direct image uploads; images must be uploaded to an image hosting service first, and then the image link can be used.
For more detailed API information, please refer to the [inBox API Documentation](https://doc.gudong.site/inbox/api.html).
## Processing Logic
When a user sends a request to create a note via the MCP client, the service processes it according to the following logic:
1. Parse the user input to identify the title (if any) and content.
2. Call the inBox API, directly passing the `title` and `content` parameters.
3. Return the processing result and a summary of the note content.
Users can explicitly specify the title in the conversation, for example: "Help me take a note, titled 'TypeScript Learning': This is the content...", and the service will automatically extract the title part.
## Limitations
- The inBox API request rate is limited to a maximum of 50 requests per day.
- Note content supports a maximum of 3000 characters.
- PRO users of inBox are required to use the API features.
## Obtaining inBox API Configuration
1. Open the inBox application.
2. Go to [Settings] -> [Account] -> [API].
3. Obtain your exclusive API configuration information.
## Contribution Guidelines
Contributions are welcome! Please submit Issues and Pull Requests to help improve this project. Before submitting a PR, please ensure that:
1. The code compiles with TypeScript.
2. All features are tested.
3. Relevant documentation is updated.
## Changelog
### v0.1.0
- Initial version release
- Supports basic note creation functionality
- Supports both Token and full URL configuration methods
- Added support for Inspector debugging tool
## Author
gudong - [Personal Homepage](https://gudong.site)
## Related Projects
- [inBox](https://inbox.gudong.site) - A simple and easy-to-use note service
- [MCP Protocol](https://github.com/ModelContextProtocol/specification) - Model Context Protocol specification
## License
MIT
