FastSpec

A self-hostable editor for OpenAPI specifications: write specs in a form editor or as YAML/JSON, preview them with Swagger UI, lint them with Spectral, keep versions and diff them — and let AI agents work with them over MCP.

• Form editor and code editor (Monaco, YAML or JSON) for OpenAPI 3.0 and 3.1. Import existing files, download as YAML or JSON, or start from an example.
• Live preview with Swagger UI.
• Linting with Spectral: the standard spectral:oas rules plus your own rulesets, per spec.
• Versions and diffs: save versions, compare any two, copy the diff as Markdown.
• MCP server so AI agents (Claude Code and other MCP clients) can read, write, version, lint and compare your specs, with scoped API keys.
• Runs anywhere: one Docker image, SQLite or Postgres, no sign-in for single-user setups, any OpenID Connect provider for teams.

Code editor (YAML or JSON)	Swagger UI preview

Quickstart

docker run -d --name fastspec \
  -p 127.0.0.1:8080:8080 \
  -v fastspec-data:/data \
  ghcr.io/kaseovo/fastspec:latest

Open http://localhost:8080. That's it: single-user mode, data stored in the fastspec-data volume.

For teams — Postgres, sign-in with Google/Keycloak/Authentik/Okta/Entra/ GitLab, running behind a reverse proxy — see docs/SELF_HOSTING.md.

Connect an AI agent

Create an API key in the app (key icon, API keys), then, for Claude Code:

claude mcp add --transport http fastspec http://localhost:8080/mcp \
  --header "Authorization: Bearer <your API key>"

Any MCP client that supports streamable HTTP works the same way.

Development

Requirements: Python 3.12, Node.js 22. Docker is only needed to build the image.

make setup   # .venv + backend and frontend dependencies
make dev     # backend (auto-reload) + Vite → http://localhost:5173/specs/
make test    # backend (pytest) and frontend (vitest) suites
make help    # everything else

make dev runs in single-user mode with SQLite in ./.data. To try sign-in or Postgres locally, copy .env.example to .env and adjust it.

Path	What's there
backend/	FastAPI app, MCP server (fastmcp_server/), Alembic migrations, tests
frontend/	Vue 3 + PrimeVue single-page app
infra/	AWS CDK stacks for the serverless deployment
docs/	Guides and architecture decision records (docs/adr/)

The backend's interactive API docs are at /docs on a running instance.

Documentation

• Self-hosting — install, sign-in, Postgres, reverse proxy, MCP, backups, configuration
• Authentication — sign-in modes, sessions, API keys
• HTTP API — base paths and authentication (full reference at /docs on any instance)
• Custom lint rules
• Deployment — including the AWS serverless setup
• Architecture, glossary and decisions
• Contributing, releasing, changelog, roadmap

Hosted version

FastSpec also runs as a hosted service at fastspec.kaseovo.com, if you'd rather not run it yourself.

License

GNU Affero General Public License v3.0. You can use, modify and self-host FastSpec freely; if you offer a modified version to others over a network, you must make your changes available under the same license.