Second Brain OS MCP Server for Claude Desktop
npm install secondbrainos-mcp-serverThis package provides a Model Context Protocol (MCP) server for integrating Second Brain OS with Claude Desktop.
- Node.js v16 or higher
- Claude Desktop application
- A valid Second Brain OS account with the Claude MCP feature enabled
``bash`
npm install -g secondbrainos-mcp-server
After installation, run the setup command with your USER_ID and USER_SECRET:
`bash`
secondbrainos-mcp USER_ID USER_SECRET
This will:
1. Verify your account credentials
2. Confirm you have access to the Claude MCP feature
3. Create the necessary configuration files for Claude Desktop
4. Configure the server to dynamically fetch your available API endpoints
library for robust OpenAPI handling, providing:
- Support for all OpenAPI/Swagger versions (v2.0, v3.0, v3.1)
- Automatic schema conversion to a standardized format
- Better handling of complex schemas including references, nullable properties, and union types$3
- Type-safe function execution with built-in error handling
- Automatic request formatting based on OpenAPI specifications
- Support for complex parameters and nested objects$3
- Detailed error messages for debugging
- Proper handling of authentication failures, bad requests, and service errors
- Graceful fallback for unexpected errorsDevelopment
$3
1. Clone the repository:
`bash
git clone https://github.com/your-username/secondbrainos-mcp-server.git
cd secondbrainos-mcp-server
`2. Install dependencies:
bash
npm install
`3. Create a
file from the example:
`bash
cp .env.example .env
Edit .env with your actual USER_ID and USER_SECRET
`$3
To see how your OpenAPI schema is converted to MCP tools:
bash
npm run test-conversion
`This will:
- Fetch your OpenAPI schema from Second Brain OS
- Convert it to LLM function calling format
- Display all available functions and their schemas
- Show any conversion errors
- Demonstrate the MCP tool format
$3
-
- Compile TypeScript to JavaScript
- npm run dev - Run the MCP server in development mode
- npm run test-conversion - Test the OpenAPI to MCP conversion
- npm start - Run the compiled server$3
`
secondbrainos-mcp-server/
├── src/
│ ├── index.ts # Main MCP server implementation
│ └── test-conversion.ts # Schema conversion testing utility
├── build/ # Compiled JavaScript (git-ignored)
├── bin/
│ └── cli.js # CLI setup script
├── .env.example # Environment variables template
├── package.json # Package configuration
├── tsconfig.json # TypeScript configuration
└── README.md # This file
Environment Variables
The server requires the following environment variables:
-
: Your Second Brain OS user ID
- USER_SECRET: Your Second Brain OS user secret
- API_BASE_URL (optional): Override the default API base URLHow It Works
1. Schema Fetching: On startup, the server fetches your personalized OpenAPI schema from Second Brain OS
2. Schema Conversion: The
@samchon/openapi library converts the schema to an optimized format for LLM function calling
3. MCP Tools: Each API endpoint becomes an MCP tool that Claude can use
4. Function Execution: When Claude calls a tool, the server executes the corresponding API call with proper authenticationTroubleshooting
$3
1. Ensure Claude Desktop is completely quit before running the setup
2. Check the configuration file was created at the correct location
3. Review the logs at the platform-specific location mentioned during setup$3
- Verify your USER_ID and USER_SECRET are correct
- Ensure your account has the Claude MCP feature enabled
- Check that your credentials haven't expired$3
- Run npm run test-conversion to see detailed error messages
- Some complex OpenAPI features may not be supported by LLM function calling
- Check the console output for specific endpoints that failed conversionContributing
1. Fork the repository
2. Create your feature branch (
git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)MIT