Content
<p align="center">
<img src="./assets/repo/banner.png" alt="A raven with spread wings in thermal-camera colors, wired to retro computer terminals" width="100%">
</p>
# Stellar Raven
Stellar Raven is a remote MCP server on Cloudflare Workers. It gives agents two tools over one
catalog of Stellar ecosystem sources: Lumenloop, Stellar Light/Scout, Stellar Docs, and selected
ecosystem skills.
- `search` finds service operations and skills.
- `execute` runs agent-written JavaScript in a Dynamic Worker isolate with no network access.
Host-side adapters make every service call and hold every secret.
The server instructions also include a generated source-family map. Agents use it to plan which
source family can answer a question.
## Connect
Add `https://raven.stellar.org/mcp` to an MCP client that supports streamable HTTP and OAuth.
Raven is its own OAuth authorization server, and WorkOS AuthKit handles sign-in. Compatible
clients find and complete this flow automatically. An access token lasts 1 hour. Clients refresh
it automatically for 90 days, then the user signs in again.
| Page | URL |
|---|---|
| User guide and troubleshooting | https://raven.stellar.org/docs |
| Browser Playground | https://raven.stellar.org/playground |
| Terms and privacy | https://raven.stellar.org/terms |
| Health | https://raven.stellar.org/health |
For help, use the `#raven` channel in the
[Stellar Developers Discord](https://discord.gg/stellardev). To report a vulnerability, read
[SECURITY.md](./SECURITY.md).
## Run locally
1. Use Node 24 (`.nvmrc`) and run `npm ci`.
2. Create `.dev.vars` with the variable names in the `.dev.vars` step of
[`ci.yml`](./.github/workflows/ci.yml). Set `DEV_ALLOW_UNAUTHENTICATED=true` to skip OAuth.
This bypass works only for the loopback hosts `localhost`, `127.0.0.1`, `::1`, and `[::1]`.
A Lumenloop call needs a real `LUMENLOOP_API_KEY`. A Stellar Docs call needs real
`ALGOLIA_APPLICATION_ID_DOCS` and `ALGOLIA_API_KEY_DOCS` values. Without them, the call returns
an error. A Stellar Light/Scout call needs no key.
3. Run `npm run typegen`. It generates `env.d.ts` from `wrangler.jsonc` and the names in
`.dev.vars`.
4. Run `npm run dev` and connect a client to `http://localhost:8787/mcp`. Restart the server after
you edit `.dev.vars`.
The Worker reads `.dev.vars`. Maintenance scripts, such as `scripts/refresh-inventory.mjs`, read
`.env`. Git ignores both files.
## Test
```sh
npm run typecheck # tsc
npm test # unit and contract tests (offline)
npm run test:smoke # the assembled Worker and the Dynamic Worker boundary
npm run build # dry-run the Worker bundle
```
[`test/README.md`](./test/README.md) maps the test suites.
## Documentation
| Question | Document |
|---|---|
| What is in scope, and which decisions are open? | [PLAN.md](./PLAN.md) |
| How do `search` and `execute` work? | [ARCHITECTURE.md](./ARCHITECTURE.md) |
| How do I deploy and operate Raven? | [docs/operations.md](./docs/operations.md) |
| How is usage counted and retained? | [usage/README.md](./usage/README.md) |
| How do I contribute? | [CONTRIBUTING.md](./CONTRIBUTING.md) |
| How do agents work in this repository? | [AGENTS.md](./AGENTS.md) |
| How do I report a vulnerability? | [SECURITY.md](./SECURITY.md) |
## License
[Apache-2.0](./LICENSE) © 2026 Stellar Development Foundation. Third-party code, fonts, and
upstream skill content keep their own licenses. Read
[THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md).
MCP Store