IMA MCP
by W-World-Labs
README.md
# IMA MCP
A self-hosted MCP bridge for [IMA](https://ima.qq.com/) notes and knowledge bases, based on [ima-mcp-server](https://github.com/xuewolai/ima-mcp-server) under the MIT license.
Source: [W-World-Labs/ima-mcp](https://github.com/W-World-Labs/ima-mcp).
The bridge supports searching and browsing knowledge bases, reading and writing notes, importing URLs, uploading Base64 files up to 6 MiB, and direct calls to the IMA note/wiki OpenAPI. Operations use the permissions of your own IMA API credentials. File uploads have been schema-checked; they have not been verified with a real user file.
## Run from source
Use Node.js 22 or newer for development and CI. The runtime supports Node.js 18 or newer.
```sh
npm ci --ignore-scripts
npm run check
```
Obtain your own API credentials from the [IMA agent interface](https://ima.qq.com/agent-interface). Supply `IMA_CLIENT_ID`, `IMA_API_KEY` and `IMA_MCP_KEY` through your process manager or a private environment file. The server does not load `.env` files itself. Generate a separate MCP access key with:
```sh
node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"
```
Once the variables are set, run `npm start`. The server binds to `127.0.0.1:18448` and exposes Streamable HTTP at `http://127.0.0.1:18448/mcp/<your-access-key>`. It does not provide a stdio transport. Configure your MCP client to use that URL. The access key must be at least 40 characters and contain only letters, digits, `_` or `-`.
| Variable | Purpose |
| --- | --- |
| `IMA_CLIENT_ID` | Your IMA OpenAPI client ID |
| `IMA_API_KEY` | Your IMA OpenAPI API key |
| `IMA_MCP_KEY` | Independent access key protecting this MCP endpoint |
For compatibility, `IMA_OPENAPI_CLIENTID` and `IMA_OPENAPI_APIKEY` are accepted when their primary variables are absent. The final credential fallback reads `~/.config/ima/client_id` and `~/.config/ima/api_key`.
For remote clients, put the loopback service behind your own authenticated HTTPS ingress. Keep access logs from recording the full MCP path: it contains the access key. The `deploy/` units are optional Linux examples; adapt their paths and account locally. The optional tunnel unit requires a separately installed tunnel client and private tunnel configuration. No tunnel binary, credentials or production configuration are included.
## Build and release
GitHub Actions runs locked dependency installation with lifecycle scripts disabled, syntax checks and package inventory validation on pull requests and pushes. A `v<package-version>` tag on `main` additionally publishes the npm archive and its SHA-256 checksum as a GitHub Release. The workflow does not publish to npm or deploy a running server.
```sh
npm pack --ignore-scripts
```
The npm package contains only `server.mjs`, `package.json`, this README and `LICENSE`. Use a source checkout and `package-lock.json` for locked installation with `npm ci`.
## License
MIT. The upstream project's attribution is preserved in `LICENSE`.
## Third-party code and dependencies
This project is based on [xuewolai/ima-mcp-server](https://github.com/xuewolai/ima-mcp-server); its MIT attribution is retained in [LICENSE](LICENSE). The direct runtime dependency is `@modelcontextprotocol/sdk`; [package.json](package.json) and [package-lock.json](package-lock.json) record the declared and locked dependency graph. Dependencies retain their own licenses. IMA is a separately operated service and is not included in this package. Review the upstream and dependency license texts when redistributing.
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessOutdated data